Designing applications - Objects First with Java: A Practical Introduction Using BlueJ - page 469

13.3 Documentation

After identifying the classes and their interfaces, and before starting to implement the methods
of a class, the interface should be documented. This involves writing a class comment and
method comments for each class in the project. These should be described in sufficient detail to
identify the overall purpose of each class and method.

Along with analysis and design, documentation is a further area that is often neglected by be-
ginners. It is not easy for inexperienced programmers to see why documentation is so impor-
tant. The reason is that inexperienced programmers usually work on projects that only have a
handful of classes and are written in the span of a few weeks or months. A programmer can get
away with bad documentation when working on these mini-projects.

However, even experienced programmers often wonder how it is possible to write the docu-
mentation before the implementation. This is because they fail to appreciate that good docu-
mentation focuses on high-level issues such as what a class or method does rather than on
low-level issues such as exactly how it is done. This is usually symptomatic of viewing the
implementation as being more important than the design.

If a software developer wants to progress to more-interesting problems and starts to work pro-
fessionally on real-life applications, it is not unusual to work with dozens of other people on an
application over several years. The ad hoc solution of just “having the documentation in your
head” does not work anymore.

Exercise 13.9 Create a BlueJ project for the cinema booking system. Create the necessary
classes. Create method stubs for all methods.

Exercise 13.10 Document all classes and methods. If you have worked in a group, assign
responsibilities for classes to different group members. Use the javadoc format for com-
ments, with appropriate javadoc tags to document the details.

13.4 Cooperation

Pair programming Implementation of classes is traditionally done alone. Most programmers
work on their own when writing the code, and other people are brought in only after the implemen-
tation is finished, to test or review the code.
More recently, pair programming has been suggested as an alternative that is intended to produce
better-quality code (code with better structure and fewer bugs). Pair programming is also one of the
elements of a technique known as Extreme Programming . Do a web search for “pair programming”
or “extreme programming” to find out more.

Software development is usually done in teams. A clean object-oriented approach provides
strong support for teamwork, because it allows for the separation of the problem into loosely
coupled components (classes) that can be implemented independently.