Software Design and Documentation




 Coding and Software Design  Minimum Software Project Report
 General Best Practices for Coding and Documentation  Design and Performance

Coding and Software Design

Look at some long more technical documents like Java Programming Style Guidelines, Doug Lea's Java Coding Standard page or Java Code Conventions. There are many good common best practices and advices to prepare good software and documentation on similar documents.


If you write your programs in Java, follow the JavaDoc guidelines: How to Write Doc Comments for the Javadoc Tool.


The best book, a software classic on coding, and a must for any serious programmer: Code Complete: A Practical Handbook of Software Construction, 2d Ed, Steve McConnel, Microsoft Press, 960 pages, June 2004.

General Best 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 software architecture.


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.

Minimum Software Project Report

Project Proposal


A simple template including 5 aspects of a minimum software project report: Software Project Report Template.

bulletThere 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
5. Implementation

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.

The Literature 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 section.

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 progresses.

Design and Performance

bulletTo improve the performance of java programs, look at the following document: Thirty Ways to Improve the Performance of Your Java Programs, Glen McCluskey.


Home | Software Design and Documentation | Software Engineering Classics | Project Proposal

This site was last updated 10/19/15