When I teach programming, apart from pushing code readability, I try to emphasize the importance of writing decent program comments. All too often I hear students proclaim that the “code is self-documenting“. Really? The only true self-documenting code is written in Cobol, and that’s partly because of its English-like syntax, and the inability to really write obfuscated code (unless one considers the entire language to be obfuscated – and some do). It doesn’t take a lot of effort to add some comments. Not the trivial “This statement adds one to the variable index” – that *should* be common sense. What needs to be there is the stuff that when you look at it in six months time, you’ll actually know what the code does. You write a nice algorithm, code it, it works beautifully – then you abandon it only to come back months later, look at the code and wonder how it actually works. We are *all* guilty of it. And we should know better.
A program should contain the appropriate amount of instructions for humans, next to the actual code doing to the work – so that humans can understand it. The program itself doesn’t care, it strips out comments, and all the pretty whitespace we add for readability. But humans care – or at least we should care more. The purpose of a comment should be to not only explain weird and cryptic code, but also ensure that the reader always knows exactly what is happening. The worst offenders? People who write obscure, compact, unintelligible code, provide no comments, and post the code for others to use.
“Programs must be written for people to read, and only incidentally for machines to execute.”
― Halold Abelson & Julie Sussman, Structure and Interpretation of Computer Programs