Neil Fraser

For most of the past couple of decades I've been a software engineer at Google in California. Currently I'm working for New Voice in Switzerland. In my spare time I've created a mélange of open-source software. I've also built some rather unusual hardware. On rare occasions I've even been known to write something interesting.

Dumb Comments Thursday, 13 February 2025

Programming teachers are constantly pushing students to write comments. And then they are inevitably irritated when the students write comments like this:

for (var i = 0; i < 10; i++) { // Count from 0 to 9 using 'i'.
  if (i == 5) {                // Check if 'i' is 5.
    break;                     // Exit from the loop early.
  }                            // End of if statement.
}                              // End of counting loop.

This inevitably leads to a lecture about how comments should be written at a higher level, they serve no purpose if they are just describing the line. Eventually, with experience, programmers start writing useful comments.

So imagine my surprise when I suddenly found myself writing this exact style of low-level comments. After being a professional programmer for 35 years, I suddenly fell back into the commenting style of a high school student. Was I having a stroke? No, it was more interesting.

LOOP	CCS	RAND6	# Branch on the value of RAND6.
	TCF	STEP	# RAND6 > 0 (A = RAND6-1), jump to STEP
	CAF	FIVE	# RAND6 = 0, make it 5 again
STEP	TS	RAND6	# Save decremented number back to RAND6
	TCF	LOOP	# Loop again

In this case 'CCS', 'TCF', 'CAF', and 'TS' didn't initially mean much to me. So each line needed a comment to state what it is doing. However, over time these operators started becoming understandable words that I could read natively. At which point the comments started to thin out and become higher level.

We talk about 'coding', but sometimes we forget that 'code' is actually a 'code'. With experience it stops being 'code' and starts being a 'language'. But to a new programmer 'i++' needs an explicit explanation.

(So ... who recognizes that language?)

Older news: Poisson Simulator - Bureaucracy - Xendoll Lathe - Steaming out of Zurich - Archive