I remember the day my code comments died. It was 2012, I had moved up from Junior Developer to Developer. My project had started as pure R&D, then moved to prototyping, and finally to production.
As part of the work, I had to develop an algorithm to run over an incoming stream of measurements and detect outliers. Once we had settled in on our approach my supervisor asked me to write it up. You know, the old “in case you’re hit by a bus tomorrow” documentation.
I dutifully transcribed the knowledge out of my head, recounting the data, analysis, and decisions made along the way to arrive at the current implementation. I thought it would also be good, as an appendix, to list out the algorithm in pseudocode.
Pseudocode, of course, has no common syntax. I stared at the blank page, started writing out the functions and variables then stopped and asked myself “how do you write comments in pseudocode?”
This is when it hit me: You don’t. Long variable names, descriptive function names, breaking things into many small functions (or methods if you’re that way inclined) so the code becomes self-documenting. That is how you write pseudocode.
What follows immediately, of course, is the realization that this is how you should write all code. Comments should be the exception, not the rule.
There are exceptions of course - libraries and frameworks need documentation, but in my day-to-day code there are very few comments. There is no reason not to make your code self documenting - too many keystrokes? Get an editor with decent tab completion, names getting too long-winded? Your code is probably doing too much and should be broken into smaller chunks.
These days my comments are to note things that would surprise or confuse a future developer (a.k.a. me in six months time) looking through the code - i.e. This is wrong but matches the previous implementation, or we can’t use <naive approach> here because of <mitigating circumstance>.
The best code is code that tells it’s own story.