Lecture
The Legacy of Development
Developing a software system involves far more than simply writing code. Certain aspects of the project must be continuously available to development managers and outside users. We also want to preserve a record of the decisions made during analysis and design for those who will maintain the system. As noted in Chapter 5, the products of object-oriented development typically include class, object, module, and process diagrams. Taken together, these diagrams make it possible to trace their origins directly back to the initial requirements for the system. Process diagrams correspond to programs, which are the root modules of the module diagram. Each module represents the implementation of some combination of classes and objects, which in turn can be found on the class and object diagrams, respectively. Finally, object diagrams represent scenarios defined by the requirements, and class diagrams show the key abstractions that form the vocabulary of the problem domain.
The Content of Documentation
Documenting the architecture of a system is important, but producing it must not be the driving force of the development process: documentation is an essential, yet not the foremost, product. It is important to remember that documentation is a living product, and it must be allowed to evolve along with the project's releases. Together with the program text, the accompanying documentation serves as the basis for conducting many formal and informal reviews.
What should be documented? Obviously, the documentation presented to the end user must include instructions for installing and using each release. In addition, the results of analysis must be documented, so as to capture the semantics of the system's function points in a sequence of scenarios. Documentation on the architecture and implementation must also be maintained, in order to convey to the development team a common vision of the system and the details of its architecture, as well as to preserve information about all strategic decisions - this undoubtedly makes the system easier to evolve and adapt.
The documentation on architecture and implementation must describe:
The worst documentation one can produce for an object-oriented system is a class-by-class explanation of the meaning of each individual method. This approach yields mountains of useless paper that no one reads and no one trusts, and in the process the most important architectural decisions are lost - the ones that reach beyond individual classes and manifest themselves in the collaboration of classes and objects. It is far better to document these high-level structures in the language of diagrams, using the notation described above but without explicit programming-language statements, and to refer developers to the interfaces of the most important classes for the tactical details.
Comments