Ramblings on Software Architecture: The Code is the Design

There are at least two problems with using the code as the design. The first is that
most modern languages have insufficient richness to actually describe the design.

For a simple example, take an object with member that is a pointer/reference to
another object. You cannot tell just by looking at the declaration of the pointer if the
reference is to an object that is an intimate component or just some casual reference.
(Our project coding standard requires the comment "//owned" to be placed next to
declarations to make this relationship clearer.)

The second problem is that you have no idea of the correctness of the code. We used
to jokingly say on this project that it was entirely bug free since the code is the design
and it is, therefore, by definition fully in compliance with the design. The Eiffel
language tries to overcome this by explicitly setting up a contract for each function,
but it is not exactly a common development language.

To summarize, the code is an exact description of what the program does, but a very
poor description of what it was intended to do.

Some languages (Java) compound the situation by providing very little clue about the
overall structure. A directory containing 70 Java classes, most of which have a main()
method, can take quite a while to analyse.

The market for CASE tools to assist with design is a good clue that the languages
themselves are not up to the task of doing the higher level design tasks.

Technology

One of the issues with design is that it is expensive to create and maintain. While I
am of the opinion that it is even more expensive to not have this documentation we
should consider some ways of improving the efficiency of the process.

An important consideration is that the design must be available to the maintainers of
the system. If the design is captured in some expensive CASE tool that the client is
not prepared to keep licensed then the design effectively becomes a non-maintainable
paper document. Such a CASE tool should be part of the deliverable system, just like
the DBMS, for example.

Conclusion

While it may be possibly to skip a lot of design documents, or to just whiteboard
them while the system is being developed, they are likely to be sorely missed
during the maintenance phase of the project. Capturing the intent of the programs
allows us to determine their correctness.

The cost of making changes during maintenance is usually far higher than for making
them in the development process. A large part of this cost arises from the need to
understand how the change will impact the existing system. Hence the more
information that is available the better.

In anything but the most trivial of projects, the design process remains the core of
software development. Documenting that design allows it to be comunicated to those
who need to understand the intent of the programs.