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 sometime after we have written 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:
u = fun4you(u, i, 33, 28); // ;) ++i; // incrementing i
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.
In the second line, the comment is superfluous and states what any even not-so-experienced programmer knows about the ++ operator.
Compare that to the following:
/* 33 and 28 are suitable because they are coprime. */ u = nextApprox(u, i, 33, 28); /* Theorem 3 ensures that we may move to the next step. */ ++i;