Suggestion to add a section or appendix on code documentation #3
Description
Suggestion to add a section or appendix on code documentation
I suggest that a dedicated section on documentation of code is added to the guidelines.
What are your opinions on this subject?
I will elaborate a bit on the reason why I suggest a section on documentation:
From the https://github.com/isocpp/CppCoreGuidelines/blob/master/README.md: "Please remember that one purpose of a guideline is to help someone who is less experienced or coming from a different background or language to get up to speed."
Good documentation is essential for less experienced programmers to getting up to speed with existing code.
As a reviewer of code, in my experience it is common that you need to explain to the contributor of code that it lacks documentation in one form or another. Having support by rules in the guidelines would make it simpler to point out why the contribution does not meet the expected standard.
The guidelines as they stand today, contains some hints on how to write code with sufficient documentation, but most often this is quite implicit. For example in P3: "Express intent" https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rp-what
A common situation when I review code is that I stumble upon some very convoluted code that I need to spend quite some time to understand, and it actually ends up being something that could be replaced by just some std::sort() or std::find_if(). Now, if the original contributor had documented what the code actually achieves it would save a lot of time and effort when analyzing what actually happens. The same goes for code containing some weird ownership transfers that are undocumented. This was just a few examples.
A common excuse to not write comments/documentation is that the code should be "self-documented". Ok, but actually what this most often leads to, is that you can read what the code actually does, but not what it intend to do. This makes a big difference when the original author makes a mistake and introduces a bug. How could you as a reviewer spot the bug unless it somewhere is stated what the intent of the code actually is? It is possible, but with more effort than should have been needed.
My experience in digging in old code, is that very often the documentation, including comments explaining the non-obvious, is inferior. What usually is even more problematic is to understand old code written some time ago, by an author that already has left the company. I have no suggestion how to resolve this problem, but it could have been avoided if proper guidelines had existed at the time of writing the code.
Below follows some rules on documentation in other guideline documents that may serve as an inspiration:
JSF C++ coding standard
https://www.stroustrup.com/JSF-AV-rules.pdf
Rule AV 129 -AV 132 prescribe how code should be documented. AV Rule 130 "The purpose of every line of executable code should be explained by a comment, although one comment may describe more than one line of code. "
LLVM coding standard
https://llvm.org/docs/CodingStandards.html#doxygen-use-in-documentation-comments
Google style guide
https://google.github.io/styleguide/cppguide.html#Comments