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.
Some shared context will always be unstated — in this case it's "what is a gimbal," and avoiding over-explaining is a subtle task. Sometimes in my mind I use the "new hire" test: would this info be helpful to someone who just joined the team?
I wonder if the discomfort with comments originates from the combativeness of some (bad) engineering environments, where someone asking "what is this for? Why are you doing this?" is perceived as threatening. "My work should speak for itself" might be defensive on some level.
I’m not sure I get the Guildenstern joke. Is it because he and Rosencrantz always appear together, somehow akin to P66 and P67? Or that they alternate speaking their lines? The programmers did know these guys were doomed, right?
The programmer of this section appears to have been emotionally invested in the project, I would say. Note a little lower the two comments that read “TEMPORARY, I HOPE HOPE HOPE”.
Now you’ve got me interested in the Apollo software project. The README mentions one Margaret Hamilton as the programming leader. I came across this article about her:
I love that picture of Margaret Hamilton. And sometimes those comments are very poignant! I don't think the Guildenstern thing is a joke, exactly — it looks like they named one of the modules "Guildenstern" (though there's no corresponding Rosencrantz) and are just being a bit cheeky. The Stoppard play premiered a few years before the mission, and it seems likely that someone on the team would have seen it (or was a Shakespeare lover, for that matter). You're right that it doesn't bode well that those guys died.
Yes, you’re surely on to something. I didn’t realize the play was that old. I see that it ran on Broadway for a year in 1967-1968. So that’s the right timeframe for one of the MIT programmers to go down to NYC and see it. The finished code was submitted March 1969.
I still want to think there’s some joke or significance there. I don’t imagine it was used just because it sounded good, or that it was some Shakespeare fan’s idle musing. Prior to Stoppard’s play I don’t believe much was made of those two minor characters. I think they’re mostly there to help advance the plot and maybe to show Hamlet’s ruthlessness en route to England when he discovers they’re carrying a letter from Claudius instructing the recipient to execute Hamlet, thus sealing their fates.
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.
Yes — that's exactly the kind of situation that "the code speaks for itself" can't account for.
I think the book Clean Code has a lot to answer for when it comes to the attitude that comments are a necessary evil to be avoided as much as possible. There's definitely such a thing as bad commenting, but it's usually IMO the result of bad thinking. If the comments are bad there's an excellent chance the code is also bad, because it's an indicator that the author hasn't thought very deeply about who is going to be using their system and how, and what questions they might have.
Comments are are a joy and a treasure, not a blight! If coders are writers, they need to consider their readers.
My position has been: your comments should explain why, not what, how who or when. The code itself explains the what and how, and git will take care of the who and when. If there's any doubt in your mind whatsoever that someone, including future you, won't be able to intuit why, make a comment. I get very annoyed any time I'm reading some code and thinking, "but why," and there is no answer.
Where I differ: comments absolutely should explain what and how unless it is extremely obvious (and I mean one-line obvious). I can't count the number of times I've looked at a class called something generic like UserEventMessageHandler: the author might say "it's obvious what this does! It handles user event messages!" But actually there are about six different things a "user event message" could be, and this class handles only some of them under certain circumstances, and some of them actually go to "ClientEventListener" or "NavigationMessageController." You might say: you just need better names! But the more complex the system is, the quicker those names get unmanageably long and cumbersome and make the code borderline unreadable. Just write a sentence, I beg you! Sentences are the most efficient way of explaining what something does!
Also, any codebase of any complexity is going to be full of weird special cases that address uncommon situations. So many times, I've been saved from bugs and confusion by a comment that reads, "this field will not be populated for walking trips" or a comment that contains examples of what is in a string field. Please don't make me discover this by puzzling for half an hour, after a bunch of tests start randomly failing, just tell me.
I'm actually against RidiculouslyDescriptiveThingNames in any scheme. I don't think they do anything useful at all, except give you much more text to memorize and/or make you overreliant on code completion.
But all functions, classes, objects, whatever, should be documented, along with their properties, parameters, and what have you. Like you illustrate, the name of the thing, and what it's actually used for, diverge over time. This is inevitable. I like docbloc style documentation comments, though they seem to be falling out of fashion lately judging by the terrible state of doc generators in many languages (Rust's is still pretty nice, props to the Rust team for that).
Other reasons why it's better to err on the side of more comments:
It significantly reduces the number of "the person who wrote this critical piece of infrastructure left the company and no one understands how it works, so we can never ever touch it" situations.
It also helps answer the question, "is there a reason why the code was written this way or was the author just bad at their job?" (and makes it a lot less likely that you'll have to ask that question in the first place)
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.
Some shared context will always be unstated — in this case it's "what is a gimbal," and avoiding over-explaining is a subtle task. Sometimes in my mind I use the "new hire" test: would this info be helpful to someone who just joined the team?
I wonder if the discomfort with comments originates from the combativeness of some (bad) engineering environments, where someone asking "what is this for? Why are you doing this?" is perceived as threatening. "My work should speak for itself" might be defensive on some level.
I’m not sure I get the Guildenstern joke. Is it because he and Rosencrantz always appear together, somehow akin to P66 and P67? Or that they alternate speaking their lines? The programmers did know these guys were doomed, right?
The programmer of this section appears to have been emotionally invested in the project, I would say. Note a little lower the two comments that read “TEMPORARY, I HOPE HOPE HOPE”.
Now you’ve got me interested in the Apollo software project. The README mentions one Margaret Hamilton as the programming leader. I came across this article about her:
https://www.smithsonianmag.com/smithsonian-institution/margaret-hamilton-led-nasa-software-team-landed-astronauts-moon-180971575/
I love that picture of Margaret Hamilton. And sometimes those comments are very poignant! I don't think the Guildenstern thing is a joke, exactly — it looks like they named one of the modules "Guildenstern" (though there's no corresponding Rosencrantz) and are just being a bit cheeky. The Stoppard play premiered a few years before the mission, and it seems likely that someone on the team would have seen it (or was a Shakespeare lover, for that matter). You're right that it doesn't bode well that those guys died.
Yes, you’re surely on to something. I didn’t realize the play was that old. I see that it ran on Broadway for a year in 1967-1968. So that’s the right timeframe for one of the MIT programmers to go down to NYC and see it. The finished code was submitted March 1969.
I still want to think there’s some joke or significance there. I don’t imagine it was used just because it sounded good, or that it was some Shakespeare fan’s idle musing. Prior to Stoppard’s play I don’t believe much was made of those two minor characters. I think they’re mostly there to help advance the plot and maybe to show Hamlet’s ruthlessness en route to England when he discovers they’re carrying a letter from Claudius instructing the recipient to execute Hamlet, thus sealing their fates.
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.
Yes — that's exactly the kind of situation that "the code speaks for itself" can't account for.
I think the book Clean Code has a lot to answer for when it comes to the attitude that comments are a necessary evil to be avoided as much as possible. There's definitely such a thing as bad commenting, but it's usually IMO the result of bad thinking. If the comments are bad there's an excellent chance the code is also bad, because it's an indicator that the author hasn't thought very deeply about who is going to be using their system and how, and what questions they might have.
Comments are are a joy and a treasure, not a blight! If coders are writers, they need to consider their readers.
My position has been: your comments should explain why, not what, how who or when. The code itself explains the what and how, and git will take care of the who and when. If there's any doubt in your mind whatsoever that someone, including future you, won't be able to intuit why, make a comment. I get very annoyed any time I'm reading some code and thinking, "but why," and there is no answer.
Where I differ: comments absolutely should explain what and how unless it is extremely obvious (and I mean one-line obvious). I can't count the number of times I've looked at a class called something generic like UserEventMessageHandler: the author might say "it's obvious what this does! It handles user event messages!" But actually there are about six different things a "user event message" could be, and this class handles only some of them under certain circumstances, and some of them actually go to "ClientEventListener" or "NavigationMessageController." You might say: you just need better names! But the more complex the system is, the quicker those names get unmanageably long and cumbersome and make the code borderline unreadable. Just write a sentence, I beg you! Sentences are the most efficient way of explaining what something does!
Also, any codebase of any complexity is going to be full of weird special cases that address uncommon situations. So many times, I've been saved from bugs and confusion by a comment that reads, "this field will not be populated for walking trips" or a comment that contains examples of what is in a string field. Please don't make me discover this by puzzling for half an hour, after a bunch of tests start randomly failing, just tell me.
I feel strongly about this.
I'm actually against RidiculouslyDescriptiveThingNames in any scheme. I don't think they do anything useful at all, except give you much more text to memorize and/or make you overreliant on code completion.
But all functions, classes, objects, whatever, should be documented, along with their properties, parameters, and what have you. Like you illustrate, the name of the thing, and what it's actually used for, diverge over time. This is inevitable. I like docbloc style documentation comments, though they seem to be falling out of fashion lately judging by the terrible state of doc generators in many languages (Rust's is still pretty nice, props to the Rust team for that).
Other reasons why it's better to err on the side of more comments:
It significantly reduces the number of "the person who wrote this critical piece of infrastructure left the company and no one understands how it works, so we can never ever touch it" situations.
It also helps answer the question, "is there a reason why the code was written this way or was the author just bad at their job?" (and makes it a lot less likely that you'll have to ask that question in the first place)
That all falls into what I mean by the "why" question. By example:
let c = a + b; // add a to b and store it in c
Not helpful. This is a what & how comment.
let c = a + b; // this sum will be used after a changes, so we need to get it here
Very helpful.