The code doesn't tell the whole story

We all know that writing good code is important and refactoring forces us to think about making methods smaller, more reusable and self-documenting. Some people say that comments are bad and that self-commenting code is what we should strive for. And I don't disagree. Everybody *should* strive for good code that's easy to read, understand and maintain. But the code doesn't tell the whole story.

Let's imagine that you've started work on a new project that's already underway. The major building blocks are in place and some of the functionality is up and running. You start up your development machine, download the code from the source code control system and load it up into your IDE. Where do you start?

If you don't have somebody to walk you through the codebase, you can start to make your own assumptions based upon the limited knowledge you have about the project, your expectations of how the team builds software and your knowledge of the technologies in use. Some of your assumptions might be along the following lines.

A further deep-dive through the code will help to prove your initial assumptions right or wrong, but it's also likely to leave you with a whole host of questions. Perhaps you understand what the system *does* at a high level, but you don't understand things like:

• The structure of the application.
• Where the various components are deployed at runtime and how they communicate.
• How the web-tier "knows" where to find the middle-tier.
• What approach to logging has been adopted.
• Whether any patterns and principles are in use across the codebase.
• How and where to add new functionality.
• How security has been implemented across the stack.
• How scalability is achieved.
• How the interfaces with other systems work.

Don't get me wrong, if you put the effort in you can gauge a lot from just reading through the code. I've had to review systems in the past where there has been no documentation. A combination of reading the code and asking questions has provided me with enough information to make a judgement. But it's hard work and if you don't ask the right questions, you won't get the right answers. After all, you don't know what you don't know. In effect, there's another layer of information sitting above the code that explains all of this.

This information is what should be captured in supplementary documentation and is why you should document your software architecture in a way that is complementary to the code and describes what the code itself doesn't. The code tells *a* story, but it doesn't tell the whole story.