Comments Are Code (2018)(responsibleautomation.wordpress.com)
responsibleautomation.wordpress.com
Comments Are Code (2018)
https://responsibleautomation.wordpress.com/2018/02/01/heresy-ii-comments-are-code/
47 comments
Yeah, code gets rewritten a lot because there's a intentional lack of documentation. Not entirely sure how people decided that comments are bad or that commenting is more harmful than not.
This may just be me but does anyone else actually enjoy documenting their code?
This may just be me but does anyone else actually enjoy documenting their code?
You can always make your code self explanatory, but the cost in abstraction and maintenance results sometimes a negative ROI. In such cases, writting comments is often the best solution.
There's some excitment in identifying those, and that's where I enjoy documenting the intention of my code.
There's some excitment in identifying those, and that's where I enjoy documenting the intention of my code.
>You can always make your code self explanatory
this code is done in this way because EU regulation #1374 regarding Maritime tracing.
this code seems inefficient and silly but is that way to get around a specific rendering issue in Opera Mini which needs to be supported because our project needs to support basically everything because it is a required governmental service.
This code is dealing with an issue in Safari that is supposed to be fixed by June 2024 release - please check if it is still an issue - test by doing the following...
Tldr: No, you can not always make your code self-explanatory.
this code is done in this way because EU regulation #1374 regarding Maritime tracing.
this code seems inefficient and silly but is that way to get around a specific rendering issue in Opera Mini which needs to be supported because our project needs to support basically everything because it is a required governmental service.
This code is dealing with an issue in Safari that is supposed to be fixed by June 2024 release - please check if it is still an issue - test by doing the following...
Tldr: No, you can not always make your code self-explanatory.
I enjoy commenting the code if it needs it
> As if “explains itself” weren’t a pretty damn wishy washy and relative guideline
No more wishy-washy than the concept of a comment explaining code.
No more wishy-washy than the concept of a comment explaining code.
> At this point I’m almost a specialist in doing deep dives and deciphering what spaghetti code is actually doing and why.
I don't always read comments. But when I do, it's after reading the code.
I don't always read comments. But when I do, it's after reading the code.
Clean code talks about this very well. Like all things it's a matter of doing it write or wrong.
The checklist includes:
1 are you using comments to manage obfuscated code? I.e. the comment isn't the problem it's the spaghetti code it makes the person feel entitled to write after
2 can the code just be a function with a clear name
3. Is the comment a non comment ?
<some others I forget the book is a great read>
That said. Plenty of times you need a good comment.
The checklist includes:
1 are you using comments to manage obfuscated code? I.e. the comment isn't the problem it's the spaghetti code it makes the person feel entitled to write after
2 can the code just be a function with a clear name
3. Is the comment a non comment ?
<some others I forget the book is a great read>
That said. Plenty of times you need a good comment.
Comments are very important, but I wouldn't call them "code" because they're not checked. This is one area I predict will be very important in the future, possibly with the help of LLMs: comment checkers. They'll not only ensure the comment isn't factually incorrect, but that there aren't sneaky edge cases (or not-so-sneaky, not-so-edge "oh I forgot to mention [the most important part]...") missing from the comment.
> But wait! The comments will get out of sync with the code! Well, they shouldn’t. When we perform our code reviews, we need to review the comments as well as the code. Comments should be correct, understandable, and valuable; we need to keep these points in mind during our reviews.
Problem solved, apparently.
Problem solved, apparently.
Not necessarily. If the diff is in the body of the function, a lot of review tools won't even show the unchanged comment lines above it. It's easy to overlook some drift between what the comment says a function does, and what it actually does.
Yea. Some are about smart enough to show the name of the method even if it’s out of view, I wish they could expand to include header comments.
Why use CI to check your code automatically and reliably when you can do it manually and unreliably?
CI makes a good prerequisite for code review. It's a terrible substitute for it.
But, return code 0 /s
I had a code review once where I had a comment on line 16 saying do X because Y referring to the code on line 17.
During code review, someone asked, why are you doing X on line 17?
During code review, someone asked, why are you doing X on line 17?
At the risk of sounding tautological I will say that good comments are good and bad comments are bad. Code of which it is unclear why it is the way it is should be commented. Any sort of rule that comments should be written in certain places, e.g., 'comment every public method' train people to write useless comments. In a way writing a comment is an admission of loss. I have failed to write code that was clear enough, so now I have to add a comment. Most code is quite straight forward. As a rule of thumb if you have some code that is neither highly complex nor very straightforward maybe a comment is needed once every one hundred or two hundred lines.
I'm thinking the same. I'm going so far and in most cases say "No comments in method bodies" in Merge Reviews. Why?
Typically, you are explaining statements with a comment. This is code which becomes self-documenting once you turn it into a method with a good name. Every tricky bit can now be documented via JavaDocs as well (and other language equivalents).
This also tends to avoid having 200+ line methods as well :D
Typically, you are explaining statements with a comment. This is code which becomes self-documenting once you turn it into a method with a good name. Every tricky bit can now be documented via JavaDocs as well (and other language equivalents).
This also tends to avoid having 200+ line methods as well :D
Most compelling argument is to explain "why" not "what". It's what I strive for in commit messages - in order to reconcile changes with the original intent and enable identification of bugs created through misunderstanding.
But commit history gets messy quick...I have food for thought.
But commit history gets messy quick...I have food for thought.
this is why i dislike refactoring unless there’s a legitimate change to the functionality and not just a rearrangement.
Leave the history alone for us bug spelunkers
Leave the history alone for us bug spelunkers
Refactoring doesn’t lose history. Mass migrating between source control systems loses history
It makes that history harder to read. The same piece of logic can move across files and modules and functions over the years. While it's possible to go past each of them and trace that code past those moves, it takes time and effort to do so.
I’m normally the one doing that historical spelunking, so I’m also a fan of refactors or rewritten methods that reduce the need to go back and figure out why the code is there. But I’m usually also the one doing that: maybe if other people around me did more refactoring I’d start hating it too!
We don't have any comments in the code base that I work on now.
Before, for the last couple decades of my career as a programmer, I thought that it was important to have well commented code. I don't believe that anymore. I'm fine with no comments in the code.
If you would have told me that a few years ago, I would have told you you were crazy. But after trying it, it's fine. It works. At their best, comments in code are wasted effort. That's my opinion now after 4 years of working on a code base with zero comments.
Before, for the last couple decades of my career as a programmer, I thought that it was important to have well commented code. I don't believe that anymore. I'm fine with no comments in the code.
If you would have told me that a few years ago, I would have told you you were crazy. But after trying it, it's fine. It works. At their best, comments in code are wasted effort. That's my opinion now after 4 years of working on a code base with zero comments.
"At their best, comments in code are wasted effort."
Surely the "why" for anything non-obvious should be written down just as much as the code shows the "what"?
Talking about comments as "wasted effort" sounds like you view them just as something added at the end to please a manager, rather a tool to help you write correct code in the first place.
Surely the "why" for anything non-obvious should be written down just as much as the code shows the "what"?
Talking about comments as "wasted effort" sounds like you view them just as something added at the end to please a manager, rather a tool to help you write correct code in the first place.
>> sounds like you view them just as something added at the end to please a manager, rather a tool to help you write correct code in the first place
No, I've just worked for a long time where comments were required, and there was an effort in code reviews to make sure the comments were detailed and correct, and I've worked in a zero comment code base, and I don't see any difference. They just don't add value in my limited experience with one code base without comments for the last four years and with several code bases with comments for the 20 years before that.
It was kind of surprising to me, but that's how it turned out.
To be fair, the commits are associated with a JIRA ticket, and I can go that to figure out the "why". But I do that less than I would have expected also.
No, I've just worked for a long time where comments were required, and there was an effort in code reviews to make sure the comments were detailed and correct, and I've worked in a zero comment code base, and I don't see any difference. They just don't add value in my limited experience with one code base without comments for the last four years and with several code bases with comments for the 20 years before that.
It was kind of surprising to me, but that's how it turned out.
To be fair, the commits are associated with a JIRA ticket, and I can go that to figure out the "why". But I do that less than I would have expected also.
Ok the conclusion of this article is totally uncontroversial, and certainly not as punchy as its click-baity title…
> Yes, it’s generally better for code to be self-documenting. In lieu of being dumb for dumb’s sake, however, perhaps add some code comments to provide context for others…or perhaps your future self.
> Yes, it’s generally better for code to be self-documenting. In lieu of being dumb for dumb’s sake, however, perhaps add some code comments to provide context for others…or perhaps your future self.
When naming things you should name it what it is not what its for (call it a hammer not a nail driver) you can then make the determination of what you should/shouldn't do with it.
When writing comments, dont say what it does, say why its done that way. If the why doesnt need explination then it doesnt need comments.
Programming is theory building. Comments should only help you understand the theory not the source code. The source code is meant to help you know what the computer will do without interpretation. If you cant read the source code and know what it will do then you NEED to rewrite it. Otherwise just wtite it in assembly it will at least be faster that way.
Also dont include things that are learnable outside the context of your code. Dont explain what a state machine is in your comments. If you must, link to wikipedia or something.
When writing comments, dont say what it does, say why its done that way. If the why doesnt need explination then it doesnt need comments.
Programming is theory building. Comments should only help you understand the theory not the source code. The source code is meant to help you know what the computer will do without interpretation. If you cant read the source code and know what it will do then you NEED to rewrite it. Otherwise just wtite it in assembly it will at least be faster that way.
Also dont include things that are learnable outside the context of your code. Dont explain what a state machine is in your comments. If you must, link to wikipedia or something.
Comments are not checked by the compiler, but I have done some experiments with ChatGPT to find Python functions with code that is inconsistent with their docstrings. When comments are used in an automated way, they do become more like code.
If you write an example in Rust for example, the Rust test subsystem will assume (unless you explicitly say otherwise) that your example should work, so, it gets the same treatment as any other tests. After all, an example which doesn't work is trash.
But yes, generally the text you write in a comment isn't contemplated by the compiler.
But yes, generally the text you write in a comment isn't contemplated by the compiler.
Is it really that hard to write sensible comments?
Well, after a few decades writing software, I've come to the conclusion that yes, yes it is. But just because it can be hard to write a good comment it doesn't mean you need to agonise over it.
Here are a few "simple" examples:
What about this:
Yes, you can argue that the coder should explain why it's blank. But this depends on the context, and who the intended audience is. Again, no need to overthink it. Read it, modify it if you really think it's necessary (keeping in mind that the alternative is often no comment or empty else statement), and move on with your life.
Well, after a few decades writing software, I've come to the conclusion that yes, yes it is. But just because it can be hard to write a good comment it doesn't mean you need to agonise over it.
Here are a few "simple" examples:
// Once we receive the cancellation ack, we should automatically send the updated flow
if (releasedFlow.Status == ReleasedFlowStatus.IndicativeCancelled)
{
await _mediator.Send(new SendFlowCommand ...
What about this:
if (foo)
{
DoFoo();
}
else if (bar)
{
DoBar();
}
else
{
// Intentionally empty
}
Yes, you can argue that the coder should explain why it's blank. But this depends on the context, and who the intended audience is. Again, no need to overthink it. Read it, modify it if you really think it's necessary (keeping in mind that the alternative is often no comment or empty else statement), and move on with your life.
> I hold an unpopular stance: code comments are as important as the code itself.
It's unpopular because it is astonishingly wrong. Customer: "It does not work". Me: "The comments are correct, the code is not, let's call it a 50/50".
> code comments are critical to code readability and maintainability
Fine, but we are on another level: once the code is right, maintainability becomes important. As long as the code is wrong, fix it and just pray that your code survives long enough for another soul to get a look at it!
It's unpopular because it is astonishingly wrong. Customer: "It does not work". Me: "The comments are correct, the code is not, let's call it a 50/50".
> code comments are critical to code readability and maintainability
Fine, but we are on another level: once the code is right, maintainability becomes important. As long as the code is wrong, fix it and just pray that your code survives long enough for another soul to get a look at it!
I’m a big believer in inline code. Headerdoc kind of stuff encourages just about the correct density of comments.
I’ve learned to unwind the typical spaghetti that passes for code, these days, but every time I do, it reinforces my own posture of leaving a legacy.
Here’s my take on code documentation: https://littlegreenviper.com/miscellany/leaving-a-legacy/
I’ve learned to unwind the typical spaghetti that passes for code, these days, but every time I do, it reinforces my own posture of leaving a legacy.
Here’s my take on code documentation: https://littlegreenviper.com/miscellany/leaving-a-legacy/
> What’s the big deal about going through the list backward anyway? Perhaps nothing. But if it’s not important, then why not go through the list in a more intuitive way, i.e. starting at index 0? If it is important to go through backward, perhaps it’s important enough to document why. If we don’t comment the why, the reason, the context, we run the risk of a future author changing the algorithm and unwittingly causing some kind of issue because the algorithm ran “better” when searching the list in reverse.
> But wait! The comments will get out of sync with the code! Well, they shouldn’t. When we perform our code reviews, we need to review the comments as well as the code. Comments should be correct, understandable, and valuable; we need to keep these points in mind during our reviews.
I'm not against such "why" comments, but if I really want to make sure such assumptions about code are preserved I strongly prefer unit tests. They don't get out of date accidentally.
> But wait! The comments will get out of sync with the code! Well, they shouldn’t. When we perform our code reviews, we need to review the comments as well as the code. Comments should be correct, understandable, and valuable; we need to keep these points in mind during our reviews.
I'm not against such "why" comments, but if I really want to make sure such assumptions about code are preserved I strongly prefer unit tests. They don't get out of date accidentally.
> I hold an unpopular stance: code comments are as important as the code itself.
It's unpopular because it is astonishingly wrong. Customer: "It does not work". Me: "The comments are correct, the code is not, let's call it a 50/50".
> code comments are critical to code readability and maintainability
Fine, but we are on another level: once the code is right, maintainability becomes important. As long as the code is wrong, fix it and just pray that your code survives long enough for another soul to get a look at it!
> code comments are critical to code readability and maintainability
Fine, but we are on another level: once the code is right, maintainability becomes important. As long as the code is wrong, fix it and just pray that your code survives long enough for another soul to get a look at it!
Tangential to the author's point, but in Elixir, documentation can literally be code - typically function usage examples that are checked along with other tests. It's a feature I wish other languages had.
https://hexdocs.pm/elixir/1.16.0/docs-tests-and-with.html#do...
https://hexdocs.pm/elixir/1.16.0/docs-tests-and-with.html#do...
I find to be true writing zig that calls into a c-api. Often c cannot express what it really wants to do, so they document it in the comments. But since zig is more expressive than c, I can translate those comments into actual zig code.
A simple example is `Foo * foo`
That could be an input pointer, out parameter, array or it might be allowed to be null.
In zig we can express each one distinctly and all combinations.
A simple example is `Foo * foo`
That could be an input pointer, out parameter, array or it might be allowed to be null.
In zig we can express each one distinctly and all combinations.
This is LinkedIn - not HN - tier content. Comments obviously aren't code, and the idea that they are "as important" is the type of grandstanding you'd perform for a non-developer audience who have no idea what code actually does.
The "why" vs "what" advice is the universal advice everyone has been giving for the last two decades.
The "why" vs "what" advice is the universal advice everyone has been giving for the last two decades.
I think everybody disparaging the value of having guidelines around reducing comments should be forced to read the script I wrote very early on in coding that started:
```
# 1.1 CSV reading
# read CSV onto a pandas dataframe
df = pd.read_csv("somefile.CSV")
```
I really wish I was joking. . . .
```
# 1.1 CSV reading
# read CSV onto a pandas dataframe
df = pd.read_csv("somefile.CSV")
```
I really wish I was joking. . . .
The comments in my code are written with code, and executing them reveals if they are valid or if the code diverged. They are the project test suite.
I have made a system where meta data is encoded in program comments. Definitely heresy!
This is an area where copilot has shone its brightest: writing (acceptable) javadoc.
I like to think that asserts are a form of active documentation
If comments are code, they should all be removed, because they do nothing, and dead code that does nothing should be removed.
I think it's fine to leave some kinds of dead code elimination to the compiler if it's useful - naming magic constants comes to mind. Technically a no-op, but very useful.
And I’ll push back against absolutist arguments about never writing about the “what” too.
So much moaning and whining about the possibility that the comment might get out of sync with the code. Oooh so scary.
Lazy reviewers are the real problem there.
At this point I’m almost a specialist in doing deep dives and deciphering what spaghetti code is actually doing and why. And I make damn sure to write comments to help out the next poor soul.