Coding and Software Design
Practices for Coding and Documentation
Write your program for people first, computers second.
(A rule from Code Complete, Steve McConnell, Microsoft Press)
This is especially true and very
important when you are writing for your course or a big project. For
example, for course projects, if your
programming style and project documentation are not good, your instructor will not try to understand what you
have done. And also, your product will not be able to be used by other people
(maybe, by your project team members). Even sometimes you may not remember
what you have done with your own code when you look at it later!
First list the names of the packages, the files (classes) in each package you have written explaining the tasks
of each file (class) with a couple of sentences (in JavaDoc comment style if you
write in Java).
Each file should have a comment header at the top with your name, a brief description
of what the program is, and any special compiling instructions.
Most classes (functions) should
be short, and each should do only one thing.
Each class (function) should have a brief comment describing what it does. It is
not necessary to comment every line, and if your code is well written,
it should not require a lot of in-line commenting. However, you should
use comments to describe any unusual code or hard to follow code or complicated
code, and describe any non-obvious variables.
Classes, objects, methods
(functions) and variables should have meaningful names, but you
can use single letters like i for loop counters and such.
Minimize the number of global variables and objects.
“A picture worths a thousand words” UML and
Drawings for Software Architecture
In your software project documentations
and project reports,
include UML diagrams and your screen captures.
It helps people to understand
and remember your application,
and shows the correctness of your program.
You can use an UML tool and a drawing program
(like MS Visio) to
document your software static and dynamic architecture.
Don’t forget “A picture worths a thousand words”.
Use similar ways (UML diagrams, drawings, screen captures, pseudo code,
comments) to explain what you have done with your code and to explain the
Last word on academic
honesty: All code must be written by you (or your project
team in team works) and you alone, except
that you can use and modify any sample code from other sources or from
class as long as you provide credit to the source.
Software Project Report
A simple template including 5 aspects of a
minimum software project report: Software Project Report
are minimum 5 aspects of a software project and its documentation
given in the template:|
1. Project Definition and Organization
2. Technical and Literature Background
3. Software Requirements and Specifications
4. System Architecture Design and Object Design
The Project Definition and
Organization should explore project overview and objectives,
project work products and their delivery dates. In this section, you may
also describe the critical success factors, the vision statement, risk
management plans, and roles of individuals on the project.
Background should summarize related technical documents,
white papers and research
literature (for senior and graduate level advanced projects) which are the back-ground of your project. For technical or
junior projects this section might be quite short.
The Software Requirements and
Specifications should give all high level, generally
non-technical, user requirements. You model the application domain
in this section. You may develop a Requirements and
Specifications document by interviewing the end users and other related
people before starting the detailed architecture design and implementation. If UML is used,
use case diagrams (also consider activity and other diagrams but at
the application domain level) are produced at this
phase. The user interface drawings and interactive user interface
prototypes are also developed at this stage.
The System Architecture Design and
Object Design should try to map out a software solution that is
implementable with the available time, people, knowledge, and computer
resources. In this section you model the solution domain. With the intended “prototyping” nature of the projects, design,
implementation and evaluation may be performed iteratively. However, there
is merit in trying to think things through before doing at each iteration.
Here detailed solution domain UML diagrams and implementation techniques
are included. The software development process used in the project and the
project resources and schedules determine the work products for this
In the Implementation phase,
you will give your project implementation platform, software tools,
development and testing processes and
techniques used in the
project. Finally, you may include the source code
with its documentation. This section is actually done online
with the development and modeling tools. For example, Together and JBuilder
can be used for this purpose. This part is always updated as the project
Design and Performance