Nobody really advocates for comments like the first example, right? So how do they get written?
My personal bugbear is garbage doxygen comments. Not only do they add a lot of zero-value comments to the code (usually restating the Identifiers they are referencing, with capitalization and punctuation added) but they also add a bunch of line noise characters for the benefit of the doxygen interpreter. These comments are required by some coding standard, so they can not be removed, no matter how useless or actively harmful they are.
I like the guide comments in the first example – they let me skim the code.
Apart from skmming, they also let me understand idioms I was unfamiliar with. For example, I had no idea what HAL_CRC_MspDeInit(hcrc); meant (what’s Msp?) and the comment /* DeInit the low level hardware */ was helpful to me.
[…] guide comments are exactly what most people believe to be completely useless comments.
They don’t state what is not clear from the code.
There are no design hints in guide comments.
Guide comments do a single thing: they babysit the reader, assist him or her while processing what is written in the source code by providing clear division, rhythm, and introducing what you are going to read.
Guide comments’ sole reason to exist is to lower the cognitive load of the programmer reading some code.
[…]
Of all the comment types I analyzed so far in this blog post, I’ll admit that this is absolutely the most subjective one.
The comments in that first example definitely lowered my cognitive load. Ooon the other hand, they are on the edge of being trivial comments (another type discussed in antirez’s essay): I can see a few that I’d rewrite, and few I could remove. But I can’t deny the fact that even in this state they lowered my cognitive load.
Edit: extended the quotation to include the ‘liking these comments is subjective’ sentence, and added a bit of ‘trivial or no?’ discussion of my own.
Given all the encouragement to comment code, I wonder whether some learners are copying the heavily guided style of textbooks and tutorials, without necessarily realising that the abundance of comments in the textbook code is because the code is expected to be new and incomprehensible to the reader, not because that’s how commenting should be done.
I think that differing levels of experience with the language and/or framework can also contribute to “pointless” comments. What is obvious to an experienced engineer seems like a surprising quirk that needs commenting to a novice.
Apart from skmming, they also let me understand idioms I was unfamiliar with. For example, I had no idea what HAL_CRC_MspDeInit(hcrc); meant (what’s Msp?) and the comment /* DeInit the low level hardware */ was helpful to me.
Would it have still been helpful if I told you in advance that you were looking at code for a hardware driver, and that MSP is jargon for “microprocessor support package” – essentially, an abstraction layer for low level hardware – and has nothing to do with the specifics of the hardware in question? (the hardware that I copied from is a CRC coprocessor)
To me, it seems like that comment may have actually mislead you.
Nobody really advocates for comments like the first example, right? So how do they get written?
I honestly wrote those kinds of comments at the start. I was told that you can comment, and that comments are good. So I would have a comment quota implied in my head and I would write these useless comments.
It’s only later when I became more familiar with programming that I started getting annoyed by comments as they distract from the code itself.
I think writing good comments is an important skill that is quite subtle. It requires you to understand what is expected by other programmers and to use comments to fill in the gaps. To know that, you need to be quite familiar with the language, programming in general and the zeitgeist of a particular time and place.
Yes. I prefer reading code without documentation comments. Because they’re attached to functions, doc comments discourage holistic overviews of how functions interact, tutorial sections, or examples of using multiple functions together. As a result, the documentation is often poorer than it could be. Because good documentation comments are long, they make reading the code more difficult. And – as you said – because often doc comments are mandated, they’re present to fill a check box, and end being poor quality. Some of this is cultural, but culture still responds to nudges from tools.
My personal wish is for a tool that cross-references out-of-line reference documentation with code, checking for coverage and correct signatures.
Because they’re attached to functions, doc comments
At least with Doxygen, comments can be attached to files, modules, namespaces, and classes, and high-level overview docs can be in separate markdown files that get merged into the final output. It’s a problem of the user, not of the tooling, if a particular project does not include have doc comments that give high-level overviews.
My personal wish is for a tool that cross-references out-of-line reference documentation with code, checking for coverage and correct signatures.
That’s often really difficult to do, because example snippets are not complete compilation units. If I write puts(x), I know that x must be a char *, but it’s difficult to build a type checker for C that will infer this from a snippet. For C++, it may be undecidable.
The way that I solved this in my third book was to write a working compilation unit for each code snippet (or small set of code snippets) and markers in comments identifying them. The .tex file then pulled in snippets from things that would actually compile, but that is too much overhead for tiny inline blocks (e.g. a couple of tokens). The version that generated HTML used libclang to do complete parsing on the files and annotated the HTML with class IDs that corresponded to their token type (e.g. local variable, global variable, type name, keyword).
At that stage, you realise that your tooling is edging towards literate programming and you start to wonder whether you should just start there.
When I started writing code, I used to comment like that. In fact, I use to write things like this:
if(...) {
} // end if
Why? Well, what I knew said that comments were to explain the code. } is not very explanatory, so I felt it needed a comment.
As I became more experienced, I came to understand that context is important in explanatory power as well, and so } should not be read alone, but along with the indentation to allow you to tell what it matched with, etc. I think commenting every line of code with an obvious explanation is not a philosophy, but an expression of inexperience and believing all code to be somehow arcane.
As for doxygen & the likes, my gold standard of this kind of docs are the Go standard library docs. Together with how the Go stdlib APIs are designed (except for a few minor historical hiccups), I haven’t seen better yet. Not easy to quickly summarize how to reproduce that, but I like to think aiming for making a godoc page easy to read and understand for a newcomer is a good guiding principle.
I find that prepending these comments with TODO (or a similar but more unique string) and then allotting a time, daily or weekly, to run grep on that string and sort them all out.
I’m only a hobbyist programmer though, so my flow might be different to what works in a professional environment.
In a more professional environment, usually that sort of things is covered with a ticket tracker. It’s definitely a valid strategy for a 1-person project, however.
Nobody really advocates for comments like the first example, right? So how do they get written?
My personal bugbear is garbage doxygen comments. Not only do they add a lot of zero-value comments to the code (usually restating the Identifiers they are referencing, with capitalization and punctuation added) but they also add a bunch of line noise characters for the benefit of the doxygen interpreter. These comments are required by some coding standard, so they can not be removed, no matter how useless or actively harmful they are.
I like the guide comments in the first example – they let me skim the code.
Apart from skmming, they also let me understand idioms I was unfamiliar with. For example, I had no idea what
HAL_CRC_MspDeInit(hcrc);meant (what’s Msp?) and the comment/* DeInit the low level hardware */was helpful to me.The phrase ‘guide comment’ comes from antirez’s Writing system software: code comments.
The comments in that first example definitely lowered my cognitive load. Ooon the other hand, they are on the edge of being trivial comments (another type discussed in antirez’s essay): I can see a few that I’d rewrite, and few I could remove. But I can’t deny the fact that even in this state they lowered my cognitive load.
Edit: extended the quotation to include the ‘liking these comments is subjective’ sentence, and added a bit of ‘trivial or no?’ discussion of my own.
Given all the encouragement to comment code, I wonder whether some learners are copying the heavily guided style of textbooks and tutorials, without necessarily realising that the abundance of comments in the textbook code is because the code is expected to be new and incomprehensible to the reader, not because that’s how commenting should be done.
I think that differing levels of experience with the language and/or framework can also contribute to “pointless” comments. What is obvious to an experienced engineer seems like a surprising quirk that needs commenting to a novice.
Would it have still been helpful if I told you in advance that you were looking at code for a hardware driver, and that MSP is jargon for “microprocessor support package” – essentially, an abstraction layer for low level hardware – and has nothing to do with the specifics of the hardware in question? (the hardware that I copied from is a CRC coprocessor)
To me, it seems like that comment may have actually mislead you.
I honestly wrote those kinds of comments at the start. I was told that you can comment, and that comments are good. So I would have a comment quota implied in my head and I would write these useless comments.
It’s only later when I became more familiar with programming that I started getting annoyed by comments as they distract from the code itself.
I think writing good comments is an important skill that is quite subtle. It requires you to understand what is expected by other programmers and to use comments to fill in the gaps. To know that, you need to be quite familiar with the language, programming in general and the zeitgeist of a particular time and place.
Yes. I prefer reading code without documentation comments. Because they’re attached to functions, doc comments discourage holistic overviews of how functions interact, tutorial sections, or examples of using multiple functions together. As a result, the documentation is often poorer than it could be. Because good documentation comments are long, they make reading the code more difficult. And – as you said – because often doc comments are mandated, they’re present to fill a check box, and end being poor quality. Some of this is cultural, but culture still responds to nudges from tools.
My personal wish is for a tool that cross-references out-of-line reference documentation with code, checking for coverage and correct signatures.
At least with Doxygen, comments can be attached to files, modules, namespaces, and classes, and high-level overview docs can be in separate markdown files that get merged into the final output. It’s a problem of the user, not of the tooling, if a particular project does not include have doc comments that give high-level overviews.
That’s often really difficult to do, because example snippets are not complete compilation units. If I write
puts(x), I know thatxmust be achar *, but it’s difficult to build a type checker for C that will infer this from a snippet. For C++, it may be undecidable.The way that I solved this in my third book was to write a working compilation unit for each code snippet (or small set of code snippets) and markers in comments identifying them. The .tex file then pulled in snippets from things that would actually compile, but that is too much overhead for tiny inline blocks (e.g. a couple of tokens). The version that generated HTML used libclang to do complete parsing on the files and annotated the HTML with class IDs that corresponded to their token type (e.g. local variable, global variable, type name, keyword).
At that stage, you realise that your tooling is edging towards literate programming and you start to wonder whether you should just start there.
I won’t justify them, but the first type of comment only really bothers me when they “explain” a single line or two of code. Something like this:
Isn’t too bad, IMO, but it’s probably a good indicator that there should be a verifyCRC function.
When I started writing code, I used to comment like that. In fact, I use to write things like this:
Why? Well, what I knew said that comments were to explain the code.
}is not very explanatory, so I felt it needed a comment.As I became more experienced, I came to understand that context is important in explanatory power as well, and so
}should not be read alone, but along with the indentation to allow you to tell what it matched with, etc. I think commenting every line of code with an obvious explanation is not a philosophy, but an expression of inexperience and believing all code to be somehow arcane.As for doxygen & the likes, my gold standard of this kind of docs are the Go standard library docs. Together with how the Go stdlib APIs are designed (except for a few minor historical hiccups), I haven’t seen better yet. Not easy to quickly summarize how to reproduce that, but I like to think aiming for making a godoc page easy to read and understand for a newcomer is a good guiding principle.
And now we discuss comments on “Comments on Comments”. Is it comments all the way down?
I find myself guilty of writing some bad comments when dumping my brain state somewhere, e.g. before lunch and not removing them after refactoring.
I find that prepending these comments with
TODO(or a similar but more unique string) and then allotting a time, daily or weekly, to rungrepon that string and sort them all out.I’m only a hobbyist programmer though, so my flow might be different to what works in a professional environment.
In a more professional environment, usually that sort of things is covered with a ticket tracker. It’s definitely a valid strategy for a 1-person project, however.