5 ms·

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 lang

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
  Isn't your example a perfect case of the comments only being necessary because the code is somehow flawed?
  - sorokod 7y ago
    From the comment, it sounds like the code is doing a reasonable thing dealing with a complex problem. The complexity of the problem deserves documentation.
    - chronial 7y ago
      Code being somehow flawed and reasonable are not mutually exclusive. It wasn't stated what the actual problem was the code was solving, so I can't say whether it was complex. The code needed comments because it crossed layers – in general a sign of bad code. So the idea of "if your code needs comments, there's probably something wrong with it" definitely holds. Sometimes you need not to do bad things to handle a bad situation (e.g. handling a third party embedded & unfixable system working against the spec), but that does not invalidate the fact that comments are an indicator of "somehow flawed code".
      - sorokod 7y ago
        I understand what you are saying but personally I'd rather focus on understanding the codebase rather than on grading it. In this context, I often find comments very helpful, especially the "why" comments.
      - anilakar 7y ago
        It had to cross layers, because the original implementation was flawed. The $vendor had designed the their protocol stack well, but implemented it against the very spec they wrote – for example, the outer protocol frame length field did not take into account character escape codes which were a property of the inner protocol. Instead of a protocol stack, the escaping has to be handled with a multi-layer state machine. The vendor knows their protocol is buggy, because in their PC maintenance software they have arbitrarily chosen to start frame sequence numbering one higher than the escape character so that they can avoid triggering the bug in most cases. It still breaks down when the payload contains that prohibited escape code. Service techs are used to the whole thing randomly requiring retries and constantly joke about how repairing the $vendor's stuff has the best billable hours per work done ratio.
MaxBarraclough 7y ago
This strikes me as a good, but incomplete, taxonomy of comments. What about comments that describe our assumptions? I guess that's a special-case of 'what' comments. Such comments are often better expressed as assertions in code (i.e. adding more code to improve readability, rather than reworking the code). Assertions have the considerable advantage that they don't go stale as the code is changed. > although sometimes git blame will That's a great point. Detailed commit messages are a good way to record the 'why' points. Unlike in-code comments, they don't bloat and dilute the source. Of course, they're also less immediate. (I guess I'm not sold on comment-folding as an answer to this.) It's also a point in favour of fine-grain commits. If you squash your commits, 'git blame' becomes less able to help you track a line of code back to its original motivations.
- superhuzza 7y ago
  Personally I would consider listing assumptions as a 'why' comment. Knowing the assumptions gives the reader the context for why certain decisions were made, and why they may still be valid decisions or not.
  - MaxBarraclough 7y ago
    Come to think of it, 'assumptions' is awfully broad. I was thinking of in-code assumptions (We assume x is non-negative), but I think you're thinking of requirements-level assumptions? I agree that requirements-level assumptions (We assume the Vogon server will allow us to make at most 4 connections at any time) are exactly the sort of thing that should be captured in comments. I'm not sure there's a bright line between assumptions and requirements here, really. My other point there was that any non-trivial code-level assumption that can reasonably be captured with an assert, should be captured with an assert, in preference over a comment.
    - mason55 7y ago
      If you’re assuming x is non-negative I would want to know why. Is it a function of what x represents in the real world? Is it something that we agreed on but there’s no physical reason x can’t be negative? Did the dev just assume x can’t be negative because it was easy and no one ever talked about it? And if the code looks like it assume x will never be negative but there are no comments explaining why then I’ll assume it just wasn’t thought about/discussed at all and know to be careful around this code. That way when I go to update this code in the future I know if and why I have to worry about if x could be negative now.
UncleMeat 7y ago
Plenty of "what" comments are valuable. A whole lot of my code is prepended by a few paragraphs describing some algorithm from a paper and a link to the full thing. An outline of "this is what the whole thing end-to-end is doing" is fantastically useful.

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
Isn't your example a perfect case of the comments only being necessary because the code is somehow flawed?
- sorokod 7y ago
  From the comment, it sounds like the code is doing a reasonable thing dealing with a complex problem. The complexity of the problem deserves documentation.
  - chronial 7y ago
    Code being somehow flawed and reasonable are not mutually exclusive. It wasn't stated what the actual problem was the code was solving, so I can't say whether it was complex. The code needed comments because it crossed layers – in general a sign of bad code. So the idea of "if your code needs comments, there's probably something wrong with it" definitely holds. Sometimes you need not to do bad things to handle a bad situation (e.g. handling a third party embedded & unfixable system working against the spec), but that does not invalidate the fact that comments are an indicator of "somehow flawed code".
    - sorokod 7y ago
      I understand what you are saying but personally I'd rather focus on understanding the codebase rather than on grading it. In this context, I often find comments very helpful, especially the "why" comments.
    - anilakar 7y ago
      It had to cross layers, because the original implementation was flawed. The $vendor had designed the their protocol stack well, but implemented it against the very spec they wrote – for example, the outer protocol frame length field did not take into account character escape codes which were a property of the inner protocol. Instead of a protocol stack, the escaping has to be handled with a multi-layer state machine. The vendor knows their protocol is buggy, because in their PC maintenance software they have arbitrarily chosen to start frame sequence numbering one higher than the escape character so that they can avoid triggering the bug in most cases. It still breaks down when the payload contains that prohibited escape code. Service techs are used to the whole thing randomly requiring retries and constantly joke about how repairing the $vendor's stuff has the best billable hours per work done ratio.

MaxBarraclough 7y ago

This strikes me as a good, but incomplete, taxonomy of comments. What about comments that describe our assumptions? I guess that's a special-case of 'what' comments. Such comments are often better expressed as assertions in code (i.e. adding more code to improve readability, rather than reworking the code). Assertions have the considerable advantage that they don't go stale as the code is changed. > although sometimes git blame will That's a great point. Detailed commit messages are a good way to record the 'why' points. Unlike in-code comments, they don't bloat and dilute the source. Of course, they're also less immediate. (I guess I'm not sold on comment-folding as an answer to this.) It's also a point in favour of fine-grain commits. If you squash your commits, 'git blame' becomes less able to help you track a line of code back to its original motivations.

superhuzza 7y ago
Personally I would consider listing assumptions as a 'why' comment. Knowing the assumptions gives the reader the context for why certain decisions were made, and why they may still be valid decisions or not.
- MaxBarraclough 7y ago
  Come to think of it, 'assumptions' is awfully broad. I was thinking of in-code assumptions (We assume x is non-negative), but I think you're thinking of requirements-level assumptions? I agree that requirements-level assumptions (We assume the Vogon server will allow us to make at most 4 connections at any time) are exactly the sort of thing that should be captured in comments. I'm not sure there's a bright line between assumptions and requirements here, really. My other point there was that any non-trivial code-level assumption that can reasonably be captured with an assert, should be captured with an assert, in preference over a comment.
  - mason55 7y ago
    If you’re assuming x is non-negative I would want to know why. Is it a function of what x represents in the real world? Is it something that we agreed on but there’s no physical reason x can’t be negative? Did the dev just assume x can’t be negative because it was easy and no one ever talked about it? And if the code looks like it assume x will never be negative but there are no comments explaining why then I’ll assume it just wasn’t thought about/discussed at all and know to be careful around this code. That way when I go to update this code in the future I know if and why I have to worry about if x could be negative now.

UncleMeat 7y ago

Plenty of "what" comments are valuable. A whole lot of my code is prepended by a few paragraphs describing some algorithm from a paper and a link to the full thing. An outline of "this is what the whole thing end-to-end is doing" is fantastically useful.