Code

Although other sections of the documentation describe the overall architecture of the software, often you'll want to present lower level details to explain how things work. This is what the code section is for. Some software architecture documentation templates call this the "implementation view" or the "development view".

Intent

The purpose of the code section is to describe the implementation details for parts of the software system that are important, complex, significant, etc. Examples include:

  • Generating/rendering HTML: a short description of the framework that was created for generating HTML, including the major classes and concepts.
  • Data binding: the approach to updating business objects as the result of HTTP POST requests.
  • Multi-page data collection: a short description of the framework used for building forms that spanned multiple web pages.
  • Web MVC: an example usage of the web MVC framework being used.
  • Security: the approach to using Windows Identity Foundation (WIF) for authentication and authorisation.
  • Domain model: an overview of the important parts of the domain model.
  • Component framework: a short description of the framework that we built to allow components to be reconfigured at runtime.
  • Configuration: a short description of the standard component configuration mechanism in use across the codebase.
  • Architectural layering: an overview of the layering strategy and the patterns in use to implement it.
  • Exceptions and logging: a summary of the approach to exception handling and logging across the various architectural layers.
  • Patterns and principles: an explanation of how patterns and principles are implemented.
  • ...

Structure

Keep it simple, with a short section for each element that you want to describe and include diagrams if they help the reader. For example, a high-level UML class and/or sequence diagram can be useful to help explain how a bespoke/hand-written in-house framework works. Resist the temptation to include all of the detail though, and don't feel that your diagrams need to show everything. Instead, spend a few minutes sketching out a high-level UML class diagram that shows selected (important) attributes and methods rather than using the complex diagrams that can be generated automatically from your codebase with UML tools or IDE plugins. Keeping any diagrams at a high-level of detail means that they're less volatile and remain up to date for longer because they can tolerate small changes to the code and yet remain valid.

Motivation

The motivation for writing this section is to ensure that everybody understands how the important/significant/complex parts of the software system work so that they can maintain, enhance and extend them in a consistent and coherent manner. This section also helps new members of the team get up to speed quickly.

Audience

The audience for this section is predominantly the technical people in the software development team.

Required

No, but there are usually parts of a large, non-trivial software system that can benefit from some explanation.