Chapter 10. Organization and documentation
This chapter covers
- How to document interfaces
- How to explain implementations
Being an important societal, cultural, and economic activity, programming needs a certain form of organization to be successful. As with coding style, beginners tend to underestimate the effort that should be put into code and project organization and documentation: unfortunately, many of us have to go through the experience of reading our own code some time after we wrote it, and not having any clue what it was all about.
Documenting or, more generally, explaining program code is not an easy task. We have to find the right balance between providing context and necessary information and boringly stating the obvious. Let’s have a look at the two following lines:
1 u = fun4you(u, i, 33, 28); // ;)
2 ++i; // incrementing i
!@%STYLE%@!
{"css":"{\"css\": \"font-weight: bold;\"}","target":"[[{\"line\":0,\"ch\":0},{\"line\":0,\"ch\":1}],[{\"line\":0,\"ch\":29},{\"line\":0,\"ch\":30}],[{\"line\":1,\"ch\":0},{\"line\":1,\"ch\":1}]]"}
!@%STYLE%@!
The first line isn’t good, because it uses magic constants, a function name that doesn’t tell what is going on, and a variable name that does not have much meaning, at least to me. The smiley comment indicates that the programmer had fun when writing this, but it is not very helpful to the casual reader or maintainer.