6 ms·

Lesson: adding comments explaining what you think the code us doing today arent helpful. Observation: many comments explaining what the code is doing don't mat

Lesson: adding comments explaining what you think the code us doing today arent helpful. Observation: many comments explaining what the code is doing don't match what the code is doing after a few check-ins. E.G., I've seen variations on //Add 1 to x x+=2; too many times to count.

snarf21 4y ago
Agreed, I've moved to only commenting WHY the function exists. The what can be stepped through. The why gives insight into intent, purpose and origin.
superbatfish 4y ago
Some people like granular comments, and some people only want high-level comments. I’ve long suspected that both camps are correct, because they’re using different languages. A single line of Python data analysis code is often worth 20 lines of C++. If you would be willing to add one comment per 20 lines in C++, then nearly every line of your pandas gobbledygook is worth commenting. Terse code is good, but that doesn’t necessarily mean the comments should be terse (or absent).
marginalia_nu 4y ago
In general, I feel comments should explain why the code is the way it is, not what it does.
- doublerabbit 4y ago
  Exactly, understanding the mind-set knowledge of piece of code is important to keep the cogs turning.
sdenton4 4y ago
Usually you can check the commit history for the unexpected line to figure out what's up, though, to let you figure out if the bug is in the code or the comment. Comments that have the same content as the code but written in English will have code drift problems. But most comments aren't like this; they can provide context or explain what's happening at a higher level, ideally.
- danuker 4y ago
  Indeed, comments should answer the "why". But ideally the comments should be executable, as unit tests, making you read them if and only if you break them. For this to be a tolerable development experience, test as much as you can while keeping your tests away from slow dependencies like networking, DB, disk I/O..., and try to keep tests relevant to what you're modifying executable locally in a few seconds. Maybe even refactor your app to have dependencies at the top, so that most code doesn't have access to them.
  - TeMPOraL 4y ago
    > But ideally the comments should be executable, as unit tests For the kinds of comments that answer the "why", if we could do that, we wouldn't need the actual code in the first place. > making you read them if and only if you break them. A good "why" comment is supposed to inform you beforehand, so you can make changes effectively and without introducing extra bugs in the process. Unit tests are more of a safety net.
    - dhosek 4y ago
      I’m imagining the poster is thinking about things like rust doctests where code in the comments will be executed as tests when you run cargo test on the project. It’s a nice way of being able to ensure that (at least part of) the documentation will correspond to the behavior of the code.
      - danuker 4y ago
        I am thinking of any fast unit test system. Going in seconds from red to green is a thrill.
        TeMPOraL 4y ago
        Unit tests suck at being documentation, and are not a good substitute for the "why" comment. They can catch some mistakes you make with the code under test, but they can't tell you why it is the way it is. At best, they can help you guess, at the cost of having to study the test code itself (which is usually much bigger than the code it tests, and often more complicated). But the thing is, the knowledge of "why" is most valuable to have before you start making changes and break some tests.
ryanmcbride 4y ago
Yeah but I've also seen things like: AddsFiveToNum(num) { return num - 5 } A bunch too. So I don't think comments are solely at fault. Self documenting code is only as good as the person who wrote it, and the people who approved it. Sometimes a comment is warranted, sometimes it's not.
- sgerenser 4y ago
  That one drives me nuts. A while back I changed some code that had a bool called “uninit” that when true, meant the value was initialized.
  - hoosieree 4y ago
    Yesterday I learned that in emacs lisp, "defvar" is a definition that is set one time only and from that point on can never be changed (i.e. can not be VARied) and "defconst" is a definition that can be changed (i.e. is not CONSTant). Naming things is hard.
BobbyJo 4y ago
I've completely given up on comments that aren't "here is the problem this code is solving". The comments end up being actually useful that way, and longer lived in their validity. Anything more granular than that, the code itself should make obvious.
jesse__ 4y ago
Agreed. Comments that explain in English exactly what the next line does drive me crazy. Even if the line is complicated. I pretty much only ever comment things these days when I change from one approach to another. ie. // This code is weird. I tried doing it the obvious way, but that doesn't work because .. reasons .. Sometimes, if the code is short, I'll even leave the old/obvious code there for future reference when I look at the weird code and say to myself: "This is weird! Obviously it should work in this much simpler way.."
- blowski 4y ago
  I mostly use comments to explain business rules, and why are they implemented there. # High value orders need to be approved before refund # Similar logic is also applied elsewhere, this is here # as a failsafe. if ticketValue > 500: emailCustomerSupport(ticket) else refund
- omnicognate 4y ago
  I know you by ".. reasons .." you mean "<and I add the reasons here>", but I've seen too many comments worded exactly like that. Some programmers use comments (correctly) to explain reasoning and context, some use them to redundantly say what the code already says and some, apparently, use them to apologise.
melling 4y ago
Lesson? That’s at least a 40 year old piece of advice. People used to try to force me to write comments, and I would explain this to them. “Don’t get suckered in by the comments-they terribly misleading. Debug only the code. Dave Storer Cedar Rapids, Iowa https://moss.cs.iit.edu/cs100/Bentley_BumperSticker.pdf https://moss.cs.iit.edu/cs100/Bentley_BumperSticker.pdf
- mannykannot 4y ago
  That risk also exists for identifiers, which can mislead to exactly the same degree as they can inform. To avoid this hazard, run the code through an obfuscator that substitutes meaningless identifiers, before looking at it.
- doublerabbit 4y ago
  Why not both? A comment may be terribly misleading but they explain the programmers logic to a certain function. Always handy to know. Each segment of code should have a diagram, a flow model, psuedo code, and comments. More the better.
  - kangalioo 4y ago
    No, not the more the better. Comments should be easily updatable to keep up with code changes. If every refactor involves redrawing a bunch of fancy ASCII art, you'll either get less refactors, or outdated comments
    - doublerabbit 4y ago
      That's why you keep the old comments and write the changes within. "If loop does something" #rev1 "If loop did do something, it now does something twice" #rev2 "If loop doesn't do something, it does something three times" #rev3 "we loop three times because we processing supervariables" #rev4 And you have an wrong illusion of documentation. You don't need ascii diagrams. Why not a scribble in a sketch book? Whiteboards and photography exist. And the method above doesn't require you too redraw. You've already got the first and last revision. Besides, during an documentation cycle of your projects life-cycle is where you update all documentation. > you'll either get less refactors, or outdated comments If so, you're not disciplined enough. If your project is to be handed over down the line, more documentation is better than any and any documentation is better than none.
furyofantares 4y ago
A tool like this that tells me how surprising my code is, and takes into account comments around it, might change my mind on this front. If it always works as well as in the OP it would be super useful to be able to know how surprising the code I'm writing is (and I can then judge whether that's OK with me if it's surprising code), but this would also make it hard for the code and the comments to diverge greatly. I mean, I still won't want "add 1 to x" comments of course.
biohax2015 4y ago
That is the work of a bad programmer. You should give as much attention to your comments as you do your code.
nl 4y ago
Really a good code AI would note that the comments are misleading (which is sort of what this is doing). It's actually completely achievable with today's models to look at the comment and the code immediately after it and see how surprising it is then note the comment could be incorrect.
EGreg 4y ago
I'll go further. Comments are a code smell. They mean you've probably not modularized your code enough, or named your functions and variables descriptively enough. As I've approached 20 years of coding, I began to be able to count on one hand the times when I truly need to add a comment. (I don't mean the DocBlock type comments for describing functions and class interfaces, that get compiled into docs.) To all you downvoters: please do respond with examples of comments that are are counterexamples to what I said!
- deleted 4y ago
  [deleted]
- adgjlsfhk1 4y ago
  in non performance critical code, comments usually aren't necessary but they are godsends when you need to do something tricky for performance. standard examples are things like bithacks.
cperciva 4y ago
As a code reviewer, I love seeing comments like that, because it immediately flags "someone made a mistake here". Sure, sometimes the code is right and the comment is wrong -- but sometimes the comment is right and the code is wrong, in which case the comment just saved me a lot of time.
- layer8 4y ago
  At the very least you know what the next likely alternative intended semantics is.
- SilasX 4y ago
  It's also possible that both the comment and the code are right, and there's some non-obvious reason why +=2 has the effect of adding 1 here, and is the only way to do it. (Not literally, as in this example, but something analogous.)
- nextaccountic 4y ago
  I think it was Dijkstra that said that software actually lives in the mind of the programmer, and the code is just a distorted, lossy representation of that. Anything that gives us light on their thoughts is likely to improve our understanding of the software. Bugs happens when there's a mismatch between what's going on the mind of the programmer and what the code actually does, so when we read code a primary task is to understand what the programmer thought it should do. Comments informs us what are the stuff that the programmer cares enough to write down. When we see a seemingly trivial comment, we may ask: why did they took time to write down that? Did they think there was any subtlety we aren't aware of? Or perhaps they were inexperienced with the language, to the point of having a hard time reading the code they themselves wrote? (if I put this comment on Google, will I find they copy-pasted from Stack Overflow? -- in this case, the comment may be very helpful, if only to track down that [0]) [0] but even better would be an IDE that highlighted code copy-pasted from Stack Overflow, Github repositories, etc
aledalgrande 4y ago
> what you think the code I agree with that, but it gets to the point where people police all the comments in a codebase deeming them unuseful. I think, especially in a huge codebase, explaining why there is a certain block of code is very helpful to transfer knowledge.
robbyking 4y ago
I see this a lot when departments require code be commented -- instead of why you get what, which should be obvious just by reading the code.
deleted 4y ago
[deleted]
pharmakom 4y ago
Reminds me of that saying to always take one compass or three. (Although two would be useful as a signal that something has gone wrong!)
ilyt 4y ago
Using AI to reality-check comment would be cool. But if you're using comments to explain the code, 9/10 you just wrote it in too unreadable way. Sure, some algorithms are complex enough that some comments are needed to explain the how (that's the 1/10) but in most cases the comments should explain why, not how. So instead it should be // Add the calibrated skew to compensate for latency x+=2; or whatever is the reason for the code existence.

snarf21 4y ago

Agreed, I've moved to only commenting WHY the function exists. The what can be stepped through. The why gives insight into intent, purpose and origin.

superbatfish 4y ago

Some people like granular comments, and some people only want high-level comments. I’ve long suspected that both camps are correct, because they’re using different languages. A single line of Python data analysis code is often worth 20 lines of C++. If you would be willing to add one comment per 20 lines in C++, then nearly every line of your pandas gobbledygook is worth commenting. Terse code is good, but that doesn’t necessarily mean the comments should be terse (or absent).

marginalia_nu 4y ago

In general, I feel comments should explain why the code is the way it is, not what it does.

doublerabbit 4y ago
Exactly, understanding the mind-set knowledge of piece of code is important to keep the cogs turning.

sdenton4 4y ago

Usually you can check the commit history for the unexpected line to figure out what's up, though, to let you figure out if the bug is in the code or the comment. Comments that have the same content as the code but written in English will have code drift problems. But most comments aren't like this; they can provide context or explain what's happening at a higher level, ideally.

danuker 4y ago
Indeed, comments should answer the "why". But ideally the comments should be executable, as unit tests, making you read them if and only if you break them. For this to be a tolerable development experience, test as much as you can while keeping your tests away from slow dependencies like networking, DB, disk I/O..., and try to keep tests relevant to what you're modifying executable locally in a few seconds. Maybe even refactor your app to have dependencies at the top, so that most code doesn't have access to them.
- TeMPOraL 4y ago
  > But ideally the comments should be executable, as unit tests For the kinds of comments that answer the "why", if we could do that, we wouldn't need the actual code in the first place. > making you read them if and only if you break them. A good "why" comment is supposed to inform you beforehand, so you can make changes effectively and without introducing extra bugs in the process. Unit tests are more of a safety net.
  - dhosek 4y ago
    I’m imagining the poster is thinking about things like rust doctests where code in the comments will be executed as tests when you run cargo test on the project. It’s a nice way of being able to ensure that (at least part of) the documentation will correspond to the behavior of the code.
    - danuker 4y ago
      I am thinking of any fast unit test system. Going in seconds from red to green is a thrill.
      - TeMPOraL 4y ago
        Unit tests suck at being documentation, and are not a good substitute for the "why" comment. They can catch some mistakes you make with the code under test, but they can't tell you why it is the way it is. At best, they can help you guess, at the cost of having to study the test code itself (which is usually much bigger than the code it tests, and often more complicated). But the thing is, the knowledge of "why" is most valuable to have before you start making changes and break some tests.

ryanmcbride 4y ago

Yeah but I've also seen things like: AddsFiveToNum(num) { return num - 5 } A bunch too. So I don't think comments are solely at fault. Self documenting code is only as good as the person who wrote it, and the people who approved it. Sometimes a comment is warranted, sometimes it's not.

sgerenser 4y ago
That one drives me nuts. A while back I changed some code that had a bool called “uninit” that when true, meant the value was initialized.
- hoosieree 4y ago
  Yesterday I learned that in emacs lisp, "defvar" is a definition that is set one time only and from that point on can never be changed (i.e. can not be VARied) and "defconst" is a definition that can be changed (i.e. is not CONSTant). Naming things is hard.

BobbyJo 4y ago

I've completely given up on comments that aren't "here is the problem this code is solving". The comments end up being actually useful that way, and longer lived in their validity. Anything more granular than that, the code itself should make obvious.

jesse__ 4y ago

Agreed. Comments that explain in English exactly what the next line does drive me crazy. Even if the line is complicated. I pretty much only ever comment things these days when I change from one approach to another. ie. // This code is weird. I tried doing it the obvious way, but that doesn't work because .. reasons .. Sometimes, if the code is short, I'll even leave the old/obvious code there for future reference when I look at the weird code and say to myself: "This is weird! Obviously it should work in this much simpler way.."

blowski 4y ago
I mostly use comments to explain business rules, and why are they implemented there. # High value orders need to be approved before refund # Similar logic is also applied elsewhere, this is here # as a failsafe. if ticketValue > 500: emailCustomerSupport(ticket) else refund
omnicognate 4y ago
I know you by ".. reasons .." you mean "<and I add the reasons here>", but I've seen too many comments worded exactly like that. Some programmers use comments (correctly) to explain reasoning and context, some use them to redundantly say what the code already says and some, apparently, use them to apologise.

melling 4y ago

Lesson? That’s at least a 40 year old piece of advice. People used to try to force me to write comments, and I would explain this to them. “Don’t get suckered in by the comments-they terribly misleading. Debug only the code. Dave Storer Cedar Rapids, Iowa https://moss.cs.iit.edu/cs100/Bentley_BumperSticker.pdf https://moss.cs.iit.edu/cs100/Bentley_BumperSticker.pdf

mannykannot 4y ago
That risk also exists for identifiers, which can mislead to exactly the same degree as they can inform. To avoid this hazard, run the code through an obfuscator that substitutes meaningless identifiers, before looking at it.
doublerabbit 4y ago
Why not both? A comment may be terribly misleading but they explain the programmers logic to a certain function. Always handy to know. Each segment of code should have a diagram, a flow model, psuedo code, and comments. More the better.
- kangalioo 4y ago
  No, not the more the better. Comments should be easily updatable to keep up with code changes. If every refactor involves redrawing a bunch of fancy ASCII art, you'll either get less refactors, or outdated comments
  - doublerabbit 4y ago
    That's why you keep the old comments and write the changes within. "If loop does something" #rev1 "If loop did do something, it now does something twice" #rev2 "If loop doesn't do something, it does something three times" #rev3 "we loop three times because we processing supervariables" #rev4 And you have an wrong illusion of documentation. You don't need ascii diagrams. Why not a scribble in a sketch book? Whiteboards and photography exist. And the method above doesn't require you too redraw. You've already got the first and last revision. Besides, during an documentation cycle of your projects life-cycle is where you update all documentation. > you'll either get less refactors, or outdated comments If so, you're not disciplined enough. If your project is to be handed over down the line, more documentation is better than any and any documentation is better than none.

furyofantares 4y ago

A tool like this that tells me how surprising my code is, and takes into account comments around it, might change my mind on this front. If it always works as well as in the OP it would be super useful to be able to know how surprising the code I'm writing is (and I can then judge whether that's OK with me if it's surprising code), but this would also make it hard for the code and the comments to diverge greatly. I mean, I still won't want "add 1 to x" comments of course.

biohax2015 4y ago

That is the work of a bad programmer. You should give as much attention to your comments as you do your code.

nl 4y ago

Really a good code AI would note that the comments are misleading (which is sort of what this is doing). It's actually completely achievable with today's models to look at the comment and the code immediately after it and see how surprising it is then note the comment could be incorrect.

EGreg 4y ago

I'll go further. Comments are a code smell. They mean you've probably not modularized your code enough, or named your functions and variables descriptively enough. As I've approached 20 years of coding, I began to be able to count on one hand the times when I truly need to add a comment. (I don't mean the DocBlock type comments for describing functions and class interfaces, that get compiled into docs.) To all you downvoters: please do respond with examples of comments that are are counterexamples to what I said!

deleted 4y ago
[deleted]
adgjlsfhk1 4y ago
in non performance critical code, comments usually aren't necessary but they are godsends when you need to do something tricky for performance. standard examples are things like bithacks.

cperciva 4y ago

As a code reviewer, I love seeing comments like that, because it immediately flags "someone made a mistake here". Sure, sometimes the code is right and the comment is wrong -- but sometimes the comment is right and the code is wrong, in which case the comment just saved me a lot of time.

layer8 4y ago
At the very least you know what the next likely alternative intended semantics is.
SilasX 4y ago
It's also possible that both the comment and the code are right, and there's some non-obvious reason why +=2 has the effect of adding 1 here, and is the only way to do it. (Not literally, as in this example, but something analogous.)
nextaccountic 4y ago
I think it was Dijkstra that said that software actually lives in the mind of the programmer, and the code is just a distorted, lossy representation of that. Anything that gives us light on their thoughts is likely to improve our understanding of the software. Bugs happens when there's a mismatch between what's going on the mind of the programmer and what the code actually does, so when we read code a primary task is to understand what the programmer thought it should do. Comments informs us what are the stuff that the programmer cares enough to write down. When we see a seemingly trivial comment, we may ask: why did they took time to write down that? Did they think there was any subtlety we aren't aware of? Or perhaps they were inexperienced with the language, to the point of having a hard time reading the code they themselves wrote? (if I put this comment on Google, will I find they copy-pasted from Stack Overflow? -- in this case, the comment may be very helpful, if only to track down that [0]) [0] but even better would be an IDE that highlighted code copy-pasted from Stack Overflow, Github repositories, etc

aledalgrande 4y ago

> what you think the code I agree with that, but it gets to the point where people police all the comments in a codebase deeming them unuseful. I think, especially in a huge codebase, explaining why there is a certain block of code is very helpful to transfer knowledge.

robbyking 4y ago

I see this a lot when departments require code be commented -- instead of why you get what, which should be obvious just by reading the code.

deleted 4y ago

[deleted]

pharmakom 4y ago

Reminds me of that saying to always take one compass or three. (Although two would be useful as a signal that something has gone wrong!)

ilyt 4y ago

Using AI to reality-check comment would be cool. But if you're using comments to explain the code, 9/10 you just wrote it in too unreadable way. Sure, some algorithms are complex enough that some comments are needed to explain the how (that's the 1/10) but in most cases the comments should explain why, not how. So instead it should be // Add the calibrated skew to compensate for latency x+=2; or whatever is the reason for the code existence.