Sponsored Link •
Documentation of software designs
There are many approaches to software design. Formal methodologies attempt to guide you through the process of transforming a problem domain into a solution domain. In designing Java programs, you may choose to use a formal methodology, to combine several formal methodologies, or to forgo formal methodology and design by the seat of your pants. But no matter how you attack the design phase of your software project, you should in some way document your design.
Documentation helps you keep track of your own design and helps you communicate it to others. Communicating your design to other developers before you implement can give you valuable feedback on your design early on, while it is still relatively easy to make changes. It is usually easier to correct design flaws during the design phase than it is later, during the implementation or the integration and test phases. (Note that this process of getting feedback on your design, and making the appropriate adjustments, is yet another example of iteration in software development.)
Many design methodologies include graphical conventions for describing a design. CASE (Computer Aided Software Engineering) tools often allow you to document your design as you create it. With Java, however, you have one other option. Java offers a simple way to express a software design not requiring anything that isn't a standard part of any Java development environment.
Documenting a design in code
A simple approach to design documentation is to express your design in Java code that has the structure and organization, but not the functionality, of your end product. You define and name classes and interfaces, and describe them in comments. You define the name and type of each field, and describe them in comments also. You define the name, return type, number of parameters, and parameter types of each method, but you don't define the method body. Instead of a body, you write a comment that describes what the body of the method, once implemented, will do. The comment can be pseudo-code, regular text description, or both. If you take this approach, your design will remain relatively easy to change throughout the design process.
If you do this, then at the end of the design phase you will already have a lot of Java code. For each program for which you did a user interface prototype, you'll have a framework of Java code for that program -- one that has look but no functionality. (These are the user interface classes.) You will also have a framework of Java code for each class that you designed with fields, comments, and methods with empty bodies. (These are the problem domain and data management classes.)
Presenting a design with
The Java programming environment includes a tool,
that can help you document and communicate your design. In Java, there
are three kinds of comments:
// indicates that the rest of the line is a comment.
*/ indicate that all characters
between the initial
/* and the terminating
should be ignored by the compiler.
also comment out anything between them; however, the comments between
*/ are picked up by the
javadoc tool and placed into an HTML file it generates to
document the code. Because of this, comments starting with
/** are called documentation comments, or simply doc
javadoc parses .java files and generates
several HTML files that describe classes, fields, methods, and that show
Going through the entire system without implementing methods allows you to document your design in a way that helps you during implementation. At the start of implementation, you already have source code, and that source code already contains good comments. It is a good practice to make sure your classes compile as you design them even though they don't have method bodies.
Fluidity during design
An important goal to strive for during a software design phase is fluidity. What typically occurs is that you design one area, then as you go to design another area, you realize you need to go back and make adjustments in the first area. As a result, you will want to keep things fluid, or easily changeable. If you implement one section before continuing to the next, it is harder to go back and make changes to the areas already implemented. The more code you write, the greater your investment in a particular design, and the more financially and technically (and emotionally) difficult it is to go back and change it.
If there is a simple method and you implement it during the design phase, no alarms will sound. No one will expel you from the building (at least not for that reason). The main point of not implementing the methods during the design phase is to keep the design fluid until you've thought through the whole thing. To keep it easy to go back and make changes until you've gone through the entire solution domain.