8 ms·

I've never understood this idea that comments are only necessary because the code is somehow flawed. This seems to be based on an ideal of beautiful code that b

I've never understood this idea that comments are only necessary because the code is somehow flawed. This seems to be based on an ideal of beautiful code that both tells the computer step by step what to do and at the same time paints a bigger picture and expresses the intent of the programmer. In reality though, code isn't poetry. C, Pascal, Javascript, etc. aren't meant to convey the thoughts of the programmer, but to give a machine clear instructions on what to do. Humans aren't good at reading code. If we were, natural languages would have evolved like that, but they haven't. The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient. What's more, when your code really does perfectly convey the intentions of the programmer and makes comments unnecessary, then your program is encoding information that the computer doesn't need, in a format that makes it harder for the computer to distinguish between relevant and irrelevant information.

underwater 7y ago
Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it. They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.
- gmac 7y ago
  Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do this thing is subtly wrong, or when they justify using this particular value (perhaps with a link to some outside reference). Comments are mostly hints and metadata. For example, in a recent file that deals with the database: // note: the ROW() constructor below is required in Postgres 10+ if we're updating a single column (There was a syntax change from Postgres 9 that was caught by our tests) // these are the only meaningful values in Postgres: // see https://www.postgresql.org/docs/11/sql-set-transaction.html (Justifying why we don't support the whole SQL-standard range of transaction isolation types) // on trapping the following two rollback error codes, see: // https://www.postgresql.org/message-id/1368066680.60649.YahooMailNeo@web162902.mail.bf1.yahoo.com // this is also a good read: // https://www.enterprisedb.com/blog/serializable-postgresql-11-and-beyond (An audit trail for why we catch some error codes but not others that initially look similar)
  - deleted 7y ago
    [deleted]
- jlawson 7y ago
  It takes time to "context up" on code you haven't read in a while (or ever). You have to read it, understand how the parts fit together, understand any gotchas and what purpose it serves for other modules. All this takes time. Comments are just a way of speeding up the process of "contexting up". Typically it's done by saving a bit of that mental context as a comment. Ideally you want to save a piece of context that's easy to express, but took a long time to understand in the first place.
jgtrosh 7y ago
It seems like you haven't been exposed to spaghetti code with a million comments vs well designed modular code with few but useful comments. People don't just dream up that difference, it does often change other programmers' way of thinking about the code and helps convey intent far better than exhaustive comments. It is true that people often take these ideals too blindly and their beautiful architecture brings little in comparison with simple obvious code. (I'm often a culprit there.)
- danmaz74 7y ago
  The problem comes when people go from "good code needs few comments" to "never add comments to your code".
- barrkel 7y ago
  You're mixing up two orthogonal things. Your dichotomy is false, a straw man. Code overspecifies. As long as there are programmers, the clearest code in the world should still have comments indicating intent. And comments won't save unclear code.
behnamoh 7y ago
> Humans aren't good at reading code. If we were, natural languages would have evolved like that, but they haven't. Give it some more time. I know it's far fetched, but chances are once human-computer interaction (HCI) is accessible for all humans and they transform into cyborgs (hybrid human and machine), code would be a more efficient means of communication as it is the perfect compromise between binary code (that pure machines understand) and natural languages (that pure humans understand).
- azhenley 7y ago
  As an HCI Researcher, I hope not...
  - seanmcdirmid 7y ago
    The irony is that the historical branching of PL into VPL and then finally into HCI was all about getting away from code to interact with the computer.
azernik 7y ago
Who's arguing that? OP is talking about how useless comments drown out the few truly important comments.
civility 7y ago
You can say how you wish comments were done, but in practice a section of code with a lot of comments tends to indicate unresolved complexity. The worst is when you can tell the original author used comments to indicate how they wished the code worked, but it doesn't. Sometimes the comments are from the next maintainer trying to figure out what the hell is going on because there is a bug in there somewhere. The other problem with comments is multiple maintenance. It's very common for a change to be made to the code but not the comment. Now you've got lies misleading the next poor developer who dives in there. Documentation comments can be useful, but I cringe when I see lots of comments per block or statement. > Humans aren't good at reading code. That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them.
- sgift 7y ago
  > That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them. Yeah. And people who make memory errors in C are just bad programmers. At some point people will have to accept that their preconceived notions are just that and not some mythical rule that others have to discover to find enlightenment.
  - civility 7y ago
    I guess something requiring discipline and effort makes you defensive. You can't really think all programmers are equal. How do you think the good ones got better?
- DarkWiiPlayer 7y ago
  > That's something you can get better at, but it requires discipline and effort. Find me one programmer who's as fluent in C as in any natural language.
  - civility 7y ago
    If you think I said anything like that, then you're not as good at natural language as you think. Why would I defend an argument I didn't make?
afro88 7y ago
As a developer I've gone through: 1. Commenting in the redundant way 2. Avoiding comments where possible 3. Using comments to convey intent in public APIs, and occasionally to explain how something works inline. #3 came from working totally remote for a year.
pjc50 7y ago
We need to be very clear that the specific thing the author is objecting to is mandatory javadoc - the adding of comments which are just copies of the function name in English and convey no non-obvious information. These are definitely unnecessary for those reading the code. They should only be put in if there are consumers of the API who can only read the javadoc and function signatures, not the code. (On my Visual Studio theme, comments are green on a dark grey background. What's the significance? Probably none.)
- tlrobinson 7y ago
  If JavaDoc comments are necessary for documentation but unnecessary for reading / editing the code, then perhaps the editor should deemphasize JavaDoc comments and emphasize normal comments. I think the same should be true of type annotations. They are important to the compiler and as documentation, but should be deemphasized relative to the actual logic.
  - joshtynjala 7y ago
    I found it surprising that the author didn't mention the possibility of deemphasizing doc comments at the same time that they increase the emphasis of regular comments. Doc comments have value for consumers of libraries, so I'm not always able to remove them, like the author did. However, doc comments have a slightly different syntax, so we can make regular comments prominent, like the author suggests, and we can make doc comments less prominent so they aren't distracting.
- Thiez 7y ago
  I find that adding the mandatory comments everywhere ensures that you won't forget to add that extra line of information when it does make sense. It's a good habit, like looking over your shoulder before switching lanes even when you know there's nobody there.
rkangel 7y ago
There are two sorts of comments - "What" comments and "Why" comments. "What" comments tell you what the code is doing. In a lot of cases, depending on the language, the need for these can be reduced by writing clear code. This is much easier in, say, Python than Assembly. Even in Python though, sometimes you can be doing something a bit subtle where a 2 line comment can clear things up. These comments aren't irreplaceable because with a bit of reading and work, you have all the information to work out what is happening. "Why" comments are much more important - telling the reader WHY the code is doing whatever it is that it's doing. The 'trim()' comment referenced in the article is a great example of a Why comment - all the reading around the code wouldn't give you an explanation (although sometimes git blame will). Many 'what' comments are superfluous, almost no 'why' comments are - they are the collective memory of design decisions that otherwise lives in people's heads.
- rahimnathwani 7y ago
  "all the reading around the code wouldn't give you an explanation (although sometimes git blame will)" Right, as long as the commit messages talk about the 'why' instead of the 'what'. (e.g. 'Make it look bigger on mobile', instead of 'Add META tag with viewport and scaling')
  - rkangel 7y ago
    True. I was mostly thinking of commit messages that say "Fix bug where we don't handle x" implying that this change is to handle X.
- anilakar 7y ago
  I've written some really complicated code that crossed layers (due to a third party embedded & unfixable system working against the spec) where each line had two to three comment lines explaining why the operation below was necessary. Also, I'm not sure if calling Javadoc interface documentation "redundant" and "obese" is warranted. If it feels useless, it is not verbose enough.
  - chronial 7y ago
hoorayimhelping 7y ago
>The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient. It's a great idea. One of the best. I think many people will agree with that. But there needs to be an equally effective way to keep the comments up to date. Because in my short experience programming professionally, the insidious part about comments is that as soon as one is shown to be a lie, none of them are reliable anymore. And it's very easy for a comment to become a lie as code evolves. This is why things like unit tests are more attractive as a form of documentation - if the tests lie, the build fails, forcing you to fix lies.
- galangalalgol 7y ago
  This is my primary problem with comments. I have worked in very large 20year ol code bases both when I have been on the team for most of that time and when I walked in at the end. In both cases almost half the comments are at least partially incorrect.
  - ken 7y ago
    I've worked on large, old codebases before, too, and in my experience half the functions are at least partially incorrect (i.e., have bugs), too. The solution in both cases is the same: when you find problems, fix them. Don't throw out the baby with the bathwater.
- ken 7y ago
  Maybe I'm reading the wrong programs, but I haven't seen any unit tests that were an adequate replacement for either comments or out-of-band documentation. For example, I looked up the SQLite source (which often comes up here as an example of a well-written program), picked the first source file I saw (alter.c), and one of the first comments is this: /* The principle used to locate the table name in the CREATE TRIGGER ** statement is that the table name is the first token that is immediatedly ** preceded by either TK_ON or TK_DOT and immediatedly followed by one ** of TK_WHEN, TK_BEGIN or TK_FOR. Another great one: ** Note that ON cannot be a database, table or column name, so ** there is no need to worry about syntax like ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc. What unit test would you write to convey this information? Tests can be helpful but they serve a completely different purpose. You can of course write a test to cover the same ground as these comments (and knowing SQLite, they probably did), but a unit test to poke at corner cases is nowhere near as clear as simply stating what's going on. I think the article means to suggest that one possible way to nudge programmers to keep comments up-to-date is to have editors that don't make them appear "washed out".
c3534l 7y ago
I think it's motivated reasoning. People don't want to write them and it's difficult to put yourself in the mind of someone else and try to anticipate what issues they could have reading your code. You understand it, it seems obvious to you, therefor it doesn't need comments, which just so happen not to be enjoyable to write.

underwater 7y ago

Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it. They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.

gmac 7y ago
Absolutely this. The time I find comments really valuable is when they remind me (or someone else) 18 months down the line that the other, obvious way to do this thing is subtly wrong, or when they justify using this particular value (perhaps with a link to some outside reference). Comments are mostly hints and metadata. For example, in a recent file that deals with the database: // note: the ROW() constructor below is required in Postgres 10+ if we're updating a single column (There was a syntax change from Postgres 9 that was caught by our tests) // these are the only meaningful values in Postgres: // see https://www.postgresql.org/docs/11/sql-set-transaction.html (Justifying why we don't support the whole SQL-standard range of transaction isolation types) // on trapping the following two rollback error codes, see: // https://www.postgresql.org/message-id/1368066680.60649.YahooMailNeo@web162902.mail.bf1.yahoo.com // this is also a good read: // https://www.enterprisedb.com/blog/serializable-postgresql-11-and-beyond (An audit trail for why we catch some error codes but not others that initially look similar)
- deleted 7y ago
  [deleted]
jlawson 7y ago
It takes time to "context up" on code you haven't read in a while (or ever). You have to read it, understand how the parts fit together, understand any gotchas and what purpose it serves for other modules. All this takes time. Comments are just a way of speeding up the process of "contexting up". Typically it's done by saving a bit of that mental context as a comment. Ideally you want to save a piece of context that's easy to express, but took a long time to understand in the first place.

jgtrosh 7y ago

It seems like you haven't been exposed to spaghetti code with a million comments vs well designed modular code with few but useful comments. People don't just dream up that difference, it does often change other programmers' way of thinking about the code and helps convey intent far better than exhaustive comments. It is true that people often take these ideals too blindly and their beautiful architecture brings little in comparison with simple obvious code. (I'm often a culprit there.)

danmaz74 7y ago
The problem comes when people go from "good code needs few comments" to "never add comments to your code".
barrkel 7y ago
You're mixing up two orthogonal things. Your dichotomy is false, a straw man. Code overspecifies. As long as there are programmers, the clearest code in the world should still have comments indicating intent. And comments won't save unclear code.

behnamoh 7y ago

> Humans aren't good at reading code. If we were, natural languages would have evolved like that, but they haven't. Give it some more time. I know it's far fetched, but chances are once human-computer interaction (HCI) is accessible for all humans and they transform into cyborgs (hybrid human and machine), code would be a more efficient means of communication as it is the perfect compromise between binary code (that pure machines understand) and natural languages (that pure humans understand).

azhenley 7y ago
As an HCI Researcher, I hope not...
- seanmcdirmid 7y ago
  The irony is that the historical branching of PL into VPL and then finally into HCI was all about getting away from code to interact with the computer.

azernik 7y ago

Who's arguing that? OP is talking about how useless comments drown out the few truly important comments.

civility 7y ago

You can say how you wish comments were done, but in practice a section of code with a lot of comments tends to indicate unresolved complexity. The worst is when you can tell the original author used comments to indicate how they wished the code worked, but it doesn't. Sometimes the comments are from the next maintainer trying to figure out what the hell is going on because there is a bug in there somewhere. The other problem with comments is multiple maintenance. It's very common for a change to be made to the code but not the comment. Now you've got lies misleading the next poor developer who dives in there. Documentation comments can be useful, but I cringe when I see lots of comments per block or statement. > Humans aren't good at reading code. That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them.

sgift 7y ago
> That's something you can get better at, but it requires discipline and effort. Programmers who have no intention of getting better at it think the comments will save them. Yeah. And people who make memory errors in C are just bad programmers. At some point people will have to accept that their preconceived notions are just that and not some mythical rule that others have to discover to find enlightenment.
- civility 7y ago
  I guess something requiring discipline and effort makes you defensive. You can't really think all programmers are equal. How do you think the good ones got better?
DarkWiiPlayer 7y ago
> That's something you can get better at, but it requires discipline and effort. Find me one programmer who's as fluent in C as in any natural language.
- civility 7y ago
  If you think I said anything like that, then you're not as good at natural language as you think. Why would I defend an argument I didn't make?

afro88 7y ago

As a developer I've gone through: 1. Commenting in the redundant way 2. Avoiding comments where possible 3. Using comments to convey intent in public APIs, and occasionally to explain how something works inline. #3 came from working totally remote for a year.

pjc50 7y ago

We need to be very clear that the specific thing the author is objecting to is mandatory javadoc - the adding of comments which are just copies of the function name in English and convey no non-obvious information. These are definitely unnecessary for those reading the code. They should only be put in if there are consumers of the API who can only read the javadoc and function signatures, not the code. (On my Visual Studio theme, comments are green on a dark grey background. What's the significance? Probably none.)

tlrobinson 7y ago
If JavaDoc comments are necessary for documentation but unnecessary for reading / editing the code, then perhaps the editor should deemphasize JavaDoc comments and emphasize normal comments. I think the same should be true of type annotations. They are important to the compiler and as documentation, but should be deemphasized relative to the actual logic.
- joshtynjala 7y ago
  I found it surprising that the author didn't mention the possibility of deemphasizing doc comments at the same time that they increase the emphasis of regular comments. Doc comments have value for consumers of libraries, so I'm not always able to remove them, like the author did. However, doc comments have a slightly different syntax, so we can make regular comments prominent, like the author suggests, and we can make doc comments less prominent so they aren't distracting.
Thiez 7y ago
I find that adding the mandatory comments everywhere ensures that you won't forget to add that extra line of information when it does make sense. It's a good habit, like looking over your shoulder before switching lanes even when you know there's nobody there.

rkangel 7y ago

There are two sorts of comments - "What" comments and "Why" comments. "What" comments tell you what the code is doing. In a lot of cases, depending on the language, the need for these can be reduced by writing clear code. This is much easier in, say, Python than Assembly. Even in Python though, sometimes you can be doing something a bit subtle where a 2 line comment can clear things up. These comments aren't irreplaceable because with a bit of reading and work, you have all the information to work out what is happening. "Why" comments are much more important - telling the reader WHY the code is doing whatever it is that it's doing. The 'trim()' comment referenced in the article is a great example of a Why comment - all the reading around the code wouldn't give you an explanation (although sometimes git blame will). Many 'what' comments are superfluous, almost no 'why' comments are - they are the collective memory of design decisions that otherwise lives in people's heads.

rahimnathwani 7y ago
"all the reading around the code wouldn't give you an explanation (although sometimes git blame will)" Right, as long as the commit messages talk about the 'why' instead of the 'what'. (e.g. 'Make it look bigger on mobile', instead of 'Add META tag with viewport and scaling')
- rkangel 7y ago
  True. I was mostly thinking of commit messages that say "Fix bug where we don't handle x" implying that this change is to handle X.
anilakar 7y ago
I've written some really complicated code that crossed layers (due to a third party embedded & unfixable system working against the spec) where each line had two to three comment lines explaining why the operation below was necessary. Also, I'm not sure if calling Javadoc interface documentation "redundant" and "obese" is warranted. If it feels useless, it is not verbose enough.
- chronial 7y ago

hoorayimhelping 7y ago

>The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient. It's a great idea. One of the best. I think many people will agree with that. But there needs to be an equally effective way to keep the comments up to date. Because in my short experience programming professionally, the insidious part about comments is that as soon as one is shown to be a lie, none of them are reliable anymore. And it's very easy for a comment to become a lie as code evolves. This is why things like unit tests are more attractive as a form of documentation - if the tests lie, the build fails, forcing you to fix lies.

galangalalgol 7y ago
This is my primary problem with comments. I have worked in very large 20year ol code bases both when I have been on the team for most of that time and when I walked in at the end. In both cases almost half the comments are at least partially incorrect.
- ken 7y ago
  I've worked on large, old codebases before, too, and in my experience half the functions are at least partially incorrect (i.e., have bugs), too. The solution in both cases is the same: when you find problems, fix them. Don't throw out the baby with the bathwater.
ken 7y ago
Maybe I'm reading the wrong programs, but I haven't seen any unit tests that were an adequate replacement for either comments or out-of-band documentation. For example, I looked up the SQLite source (which often comes up here as an example of a well-written program), picked the first source file I saw (alter.c), and one of the first comments is this: /* The principle used to locate the table name in the CREATE TRIGGER ** statement is that the table name is the first token that is immediatedly ** preceded by either TK_ON or TK_DOT and immediatedly followed by one ** of TK_WHEN, TK_BEGIN or TK_FOR. Another great one: ** Note that ON cannot be a database, table or column name, so ** there is no need to worry about syntax like ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc. What unit test would you write to convey this information? Tests can be helpful but they serve a completely different purpose. You can of course write a test to cover the same ground as these comments (and knowing SQLite, they probably did), but a unit test to poke at corner cases is nowhere near as clear as simply stating what's going on. I think the article means to suggest that one possible way to nudge programmers to keep comments up-to-date is to have editors that don't make them appear "washed out".

c3534l 7y ago

I think it's motivated reasoning. People don't want to write them and it's difficult to put yourself in the mind of someone else and try to anticipate what issues they could have reading your code. You understand it, it seems obvious to you, therefor it doesn't need comments, which just so happen not to be enjoyable to write.