15. The other face

This post is part of a series of posts with my personal notes about the chapters in the book “The mythical man-month” by Frederick P. Brooks. I write these posts as I read through the book, and take notes on the concepts I find more relevant. I do, however, advise reading the book to get the full benefit out of it.

Documentation is needed.

Others need to understand what our application is, what it does how it does it, how it behaves. The application code, as well, needs to be understood, not only by the machine but also by the next developer reading it.

We need to document all the way from a faraway view of the system to a detailed view of the system.

Then the question is: What and how to document?

What and how to document?

Documentation to show how to use the application

Document it in prose, even as a draft before the program is written. We need to document:

1. Purpose
   What is the main function, the reason for the program?
2. Environment
   On what machines, hardware configurations, and operating system configurations will it run?
3. Domain and range
   What domain of input is valid? What range of output can legitimately appear?
4. Functions realized and algorithms used
   Precisely what does it do?
5. Input-output formats
   Precise and complete.
6. Operating instructions
   Including normal and abnormal ending behaviour, as seen at the console and on the outputs.
7. Options
   What choices does the user have about functions? Exactly how are those choices specified?
8. Running time
   How long does it take to do a problem of specified size on a specified configuration?
9. Accuracy and checking
   How precise are the answers expected to be? What means of checking accuracy are incorporated?

Documentation to prove the application works

To guarantee and exemplify how the program works, we need a test suite, testing:

1. Mainline cases that test the program’s chief functions for commonly encountered data.
2. Barely legitimate cases that probe the edge of the input data domain, ensuring that largest possible values, smallest possible values, and all kinds of valid exceptions work.
3. Barely illegitimate cases that probe the domain boundary from the other side, ensuring that invalid inputs raise proper diagnostic messages.

Documentation needed to understand how we should modify the application

To change how an application works, to change its code, more information is needed:

1. A flow chart or subprogram structure graph;
2. References to algorithms and/or design patterns used;
3. An explanation of the layout of all files used;
4. An overview of the build process, how to trigger it and what it does;
5. The decisions made and why,  ideally using an Architectural Decision Record.

Self-documenting programs

Trying to maintain code documentation separate from the code itself is an inglorius battle. It is time consuming, unappealing, and quickly gets outdated.

The bottom line is:

1. Minimize the burden of documentation;
2. Document code within the code.

The guidelines given by Brooks are as follows:

• Use code artefacts (classes, methods, functions, variables) names as a way to convey meaning to the reader. And I would add “both domain and technical meaning, hinting algorithms and/or design patterns used“;
• Use coding standards to improve readability;
• Add short and sharp prose documentation within the code, if needed.