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:
What is the main function, the reason for the program?
On what machines, hardware configurations, and operating system configurations will it run?
- Domain and range
What domain of input is valid? What range of output can legitimately appear?
- Functions realized and algorithms used
Precisely what does it do?
- Input-output formats
Precise and complete.
- Operating instructions
Including normal and abnormal ending behaviour, as seen at the console and on the outputs.
What choices does the user have about functions? Exactly how are those choices specified?
- Running time
How long does it take to do a problem of specified size on a specified configuration?
- 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:
- Mainline cases that test the program’s chief functions for commonly encountered data.
- 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.
- 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:
- A flow chart or subprogram structure graph;
- References to algorithms and/or design patterns used;
- An explanation of the layout of all files used;
- An overview of the build process, how to trigger it and what it does;
- The decisions made and why, ideally using an Architectural Decision Record.
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:
- Minimize the burden of documentation;
- 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.