Importance of software documentation

Software evolves, and changes to software are inevitable. In general, any work done to change the software after it is in operation is considered to be maintenance. Maintenance consumes over 70% of the total life-cycle cost of a software project ¹. If you think about it for a while, you would realize how critical maintenance work is to keep the software alive. Interestingly, the act of reading code is the most time-consuming component of all maintenance activities performed by software developers.

Since readability poses such importance on maintenance of software, let’s understand how do we define it. In natural languages, readability is defined as how easy a text is to understand. In literature, readability is objectively judged by metrics like average syllables per word, average sentence length, etc. Raising the readability level of a text from mediocre to good can make the difference between success and failure of its communication goals.

Programs must be written for people to read and only incidentally for machines to execute. Thus spoke the authors of the authoritative book on software development patterns, SICP. So how do we make sure the communication goals of source code is delivered to the developers?

Source code is not documentation

You would often see software developers treat source code as the primary or at times, the only documentation. For this to manifest in practice, the code has to be sufficiently detailed and precise. But source code in its original form is not readable as plain text. As noted earlier, readability plays a huge part in making software accessible and maintainable. Any documentation that is written must be easy to understand not just by the immediate team members but also by future stakeholders. Some examples of why this is important are:

1. When interfacing with external modules, the consumer should understand the exposed interfaces by the existing module.
2. To extend a module, existing models and concepts need to be understood in detail.
3. To identify a bug and patch a fix faster, detailed documentation can be critical.

Of course, for the documentation to be effective, it must be maintained along with the code itself. When refactoring code it has to be made sure that the documentation reflects the change as well. All seasoned engineering teams put the impetus on tracking changes in documentation when the code is updated.

How to write good documentation?

Three golden rules when writing documentation are asking yourself these questions while writing comments:

1. What does this piece of code do?
2. How does it do it?
3. How does someone use it somewhere else?

When you treat comments as part of source code, make sure it’s reviewed along in the merge process. If there is one takeaway from this post, it is treating documentation equally as source code as part of review process.

Embedded documentation helps the programmer to stay within the context and understand thoroughly. It also exhibits a significant level of correlation with other conventional metrics such as software quality, code churn, etc. A code base is owned primarily by a team, not an individual. It’s important that developers put in the effort to make sure that the code they write is clear and readable. Some teams may prefer to skip code documentation in order to save time, money and effort. Keep in mind though that this might result in even more significant expenses once the product is transferred to another team or when updates are required down the line.

References

1. Software Defect Reduction Top 10 List
2. CodeAsDocumentation
3. A Survey of Improving Computer Program Readability to Aid Modification