You have named your classes, functions and variables in most
expressive and descriptive way possible. All your classes are single
responsibility, functions are short as to fit onto a single screen (relative as
that is) and variables are never reused. The code is formatted according to the
standard and it’s aesthetically impeccable (at least according to you). When all
this is done why would you put any real effort into writing comments? Your version
control system will reject a check-in if you don’t write comments on your public,
internal or protected members but that’s just for show, as you can always
simply put “TODO: Comment” and the system will happily accept it. There, policy
satisfied and who cares: it must have been some clueless apparatchik that came
up with it. Your code is so obvious that it doesn't need any comments.
The above description is a caricature but there is more
than a grain of truth in it. The code is obvious at the time of coding only
because your mental model at the time is clear and (after a lot of debugging)
matches what the code is doing. What code lacks is a way to communicate the
actual intent behind it and whomever follows you in reading it will lack this
crucial information. But more importantly, even if you had a way to perfectly
communicate intent through code, what your code will never have, indeed cannot
have is what at the end wasn't coded. The coding is an art of not only what has
been written but also what hasn't been written. We constantly decide what to
put in and what to leave out. We write, delete and rewrite all the time,
searching for most optimal solution given our constraints. Then constraints
change and we do it all over again. At the end we settle on a solution to
exclusion of all others and we have the complete rationale for it. This rationale
is one of the most important things we can teach to others and this teaching is
best done through comments, alongside the code it talks about. But a rationale should
explain not only what was left and why, but also why everything else was
excluded.
Beman Dawes, the founder of boost.org, comments:
Failure to supply
contemporaneous rationale for design decisions is a major defect in many
software projects. Lack of accurate rationale causes issues to be revisited
endlessly, causes maintenance bugs when a maintainer changes something without
realizing it was done a certain way for some purpose, and shortens the useful
lifetime of software.
Rationale is fairly
easy to provide at the time decisions are made, but very hard to accurately
recover even a short time later.
The tough part is that even when we know all this, our
mental model of what code does is too accurate for simpleminded commenting. We
have to step outside of ourselves, of our own thinking and comment code for
others (including our future selves). And so to comment is to put oneself into
other’s place and try to teach others about what’s important and what’s not
important, about what we decided to leave in and what we decided to leave out
and, above all, why these decisions were made. This is why we should
write comments in our code – not because of check-in policies but because our
job isn't only what has been coded but so much more and we should be, if
nothing else, honor bound by our craft to try to teach those that follow us and
make their work easier.
I treat all unclear, incomplete or (Turing forbid!) missing comments
as defects during code reviews. And I expect to be called out on any lack of
clarity and comprehensiveness in my own comments. It’s not perfect as our coworkers
are often steeped into the same issues and can thus understand more than a
random future maintainer. But it’s the only way to ensure that the code and
comments we write complete each other and that 10 years from now they will
still be meaningful.
