Discussion about this post

User's avatar
Frank Dent's avatar

I suppose one argument for comments would be in the adage about how if you can’t explain how something works, then you probably don’t understand it yourself. I suppose a lot of my commenting was like that: notes to the future about anything that seemed non-obvious, and also proof of sorts that I knew how the code worked.

I used to code scientific models, meaning I was using some textbook or paper’s logic and equations on how to calculate something. I felt strongly that those sources needed to be documented in the code, and also any place where I took a shortcut compared to how the equations, for example, were laid out in the text.

With the Apollo code, the first file I opened at random was GIMBAL_LOCK_AVOIDANCE.agc (Command Module version). I don’t know what this is, but I can see in the code that they’ve documented shortcuts, for example the constants that were pre-calculated, probably to avoid using a software-based math function (nowadays, the performance advantage, say, of pre-calculating a cosine, would probably be negligible with built-in floating-point co-processors).

Those are GOOD comments! What they didn’t comment, though, is the physics of this gimbal thing, and why and how they’re calculating it. But I suppose in the late 60s, the people reviewing this code would be aero engineers, who could be assumed to know that.

Interesting that the Lunar Module version of this file is shorter but more extensively commented. Fancy that.

Expand full comment
Ken's avatar

Thank you for writing this essay - I can't get over the criticism you describe. Criticism of what I expect are excellent and helpful comments!

I've been of two minds on commenting. In college, our profs taught us to comment and graded us on it. I did well enough. The goal was a thoughtful comment, one helpful to a future reader. From there on, most of my coding was embedded in systems and written in assembly. I necessarily added a lot of comments. I know I'm just restating the obvious.

My second mind emerged when I re-read my code about five years later. It was long enough for me to have learned a lot more about systems design and also long enough for me to have forgotten the specifics of the code I was reviewing. I found most of my comments unhelpful in returning the details, and some comments later proved wrong because I'd revised the underlying code and failed to either delete an erroneous comment or revise my comment. By that time, I'd also read code written by others. About half the time, comments were distracting, and only occasionally were they enlightening.

This set of experiences led me to a terrible place. One where I'd write the fewest possible comments to preserve implementation details, with the observation that the code itself was decent documentation. At this point, I was writing and scripting in Sed, Awk, TCL, C, Matlab, and Verilog, one of which is strongly typed. Well-written headers with meaningful hierarchy and careful naming were enough to keep me from forgetting what I was doing. Since most of these fragments were to automate my analog design work, I considered them all throw-away.

I'm not proud of that stage in my coding life. I did enter into the arrogant camp. No one directly suffered. My projects died with me, or in one case, patented with the code disclosed, a requirement for the preferred embodiment, preserving my crappy comments for the foreseeable future.

What never occurred to me was that my inability to write in English was the underlying problem. I believed this: if I bothered to write something down and wrote the absolute minimum wording to seem clear, I'd have effectively captured whatever I had in mind to preserve. Nothing could have been further from the truth.

An aside - Once upon a time, there was a computer peripheral definition with a committee standard. It was a detailed standard that defined the hardware interface and the command behavior. A design team very carefully implemented the standard in their product. But, when they tried to connect their device to the target system, they discovered a problem. It seemed that some commands were not executing. They found a bug in the software driver. It was a bug that depended on an implementation error for a feature in the peripheral. Eventually, the software vendor admitted to the bug, and the standards committee recognized the portions of the spec that led some vendors astray.

Since the software vendor was the "biggest dog" in the room, the design team ended up changing the hardware to allow the bug in the software to remain! The point is that multiple companies read the original spec, along with the software vendor, and many of them erred in their understanding. It is a difficult task to write things clearly.

I agree with you strongly. The overarching coding skill is learning to write well in a human language. We could argue code is law. We could teach ourselves to express our desires in a restricted language, but why? Use the restricted language for restricted tasks. And then use our native languages for what they're good for, explaining the operation of and need for the restricted task.

Expand full comment
10 more comments...

No posts