8 ms·

I agree with almost all of these viewpoints. The comment one though isn't quite right. Sometimes you just need a comment. For example, I was writing some code

I agree with almost all of these viewpoints. The comment one though isn't quite right. Sometimes you just need a comment. For example, I was writing some code to an API and the company was offering a private experimental feature. The API was JSON, but this one feature was enabled by adding a small stringified JSON object to a field of the larger JSON post body. If a developer looks at it, they'll think "this must be wrong" but with a comment that briefly mentions why, everyone will be saved some time.

rckrd 5y ago
I agree - I think I needed to add a bit more nuance, which I did in https://news.ycombinator.com/item?id=28087165 https://news.ycombinator.com/item?id=28087165
- mastersummoner 5y ago
  Appreciate the clarification. Comments can (and are) definitely overused and abused, but they absolutely have their place.
rzimmerman 5y ago
Yes I agree with the sentiment, but I think long comments are useful for explaining why a choice was made. Or an idiosyncrasy of the system like you said.
- christophergs 5y ago
  This. Comments are for why.
  - jlc 5y ago
    IMO commit messages are for why.
    - magnusmundus 5y ago
      Do you really prefer digging through years of commit messages to find why a particular line exists? It's a very impractical place for those. And good luck finding the origin of that line if there was an extensive refactor in between. Also, how do you notify a later viewer that there's a "why" they should check? A comment that says "check commit messages for this line"? :) Not to mention: you're losing the notes as soon as you move repositories, or worse, version control systems. Yes, I've hit the "SVN git migrate" wall way too many times. For that reason I even started leaving issue numbers in comments for when it's particularly important, in case we lose the commit<->ticket link down the line.
      - jlc 5y ago
        Typically, it isn't digging. It's the last commit, maybe the one before it, and I have tools for doing this (e.g., magit, fugitive). I don't notify anyone, nor do I need to. When I encounter a WTF moment, I look at the commit messages. When there's nothing there, I curse the last developer. I guess it can be fun spelunking through commit messages, though, to see when the comment was added and if it still applies.
    - FascistDonut 5y ago
      Yeah but you (or another developer) probably won't see the commit message later in the future when you come across that segment of code.
      - andrewnc 5y ago
        I think vs code has an extension that lets you see git info (committer and commit message) inline if you hover over a piece of code.
        ensiferum 5y ago
        Git lens
    - nradov 5y ago
  - cinntaile 5y ago
    Comments being for why or what is not really important imo, having strong feelings about this probably hurts more than it does good. The goal is for someone else (or you) to understand what's going on at a point in the future, you include what is needed to achieve that goal. Whether that's what or why or something else doesn't really matter. Sometimes you don't know how much you have to include, but experience and asking colleagues will help you get a better idea.
deleted 5y ago
[deleted]
gcmeplz 5y ago
Even in situations like that one, I think it's possible to avoid the comment: - setting up a type (with a comment linking to that API's documentation) - setting up a shape validator & a test that asserts that that that field is a string with the correct shape - Using a variable name that makes it clear that something intentional is happening: `const weirdlyStringifiedJSONObject = JSON.stringify(...)` A comment might still be the simplest thing to add, but it doesn't mean it's the only way to document that weirdness. Comments can be fragile compared to the same documentation expressed in code [edit: list formatting]
- jjice 5y ago
  Those definitely work, but adding a comment is the easiest and clearest way. No need to avoid comments like the plague, just avoid overuse.
- d4mi3n 5y ago
  I agree that these are all good things, but they cover the what and not the why. I find design documents useful to cover the why--something that results in a long comment in my experience is usually indicative of some non-trivial design decision.
dec0dedab0de 5y ago
By using "should" and "probably" it's acknowledging that there are exceptions. Though I don't think your example is an exception. I would refactor that part out to a seaprate function, and give it a docstring like "json in json, because the api is weird, [link to api docs]." Basically, weird things like that should be refactored into their own spot, instead of called out with a comment in the middle of something else.
- deleted 5y ago
  [deleted]
5faulker 5y ago
For a larger scale one-man project, you can also use mnemonics to keep track of what code's doing what, but that is unlikely to work out smoothly in a team-work setting.
toolslive 5y ago
sometimes a comment is needed: /* DO NOT DELETE the above test If you're on localhost and opening/closing sockets at high speed, you might end up being connected to yourself by accident. That's what you get when everything is a file and all files are represented with integers */ For example.
taf2 5y ago
10 years later I am very happy when I find I left myself a little note explaining to my future self my thinking at the time… more often then not though I’m left trying to remember those busy days building all the shiny new things
- minxomat 5y ago
  The only side projects that even have a chance of being rescued from certain death are the ones my past self was kind enough to explain.
zelos 5y ago
Exactly: I think it's almost a rule that you must comment code that does something out of the ordinary for a good reason.
WalterBright 5y ago
I find it very helpful, when implementing part of the compiler, to include a link (for D) or a paragraph number (for C) that references the corresponding specification section: https://github.com/dlang/dmd/blob/master/src/dmd/cparse.d#L591 https://github.com/dlang/dmd/blob/master/src/dmd/cparse.d#L5... Ever since the Intel CPU spec went online, I started doing this with the code generator - providing links to the man page for the instruction being used: https://github.com/dlang/dmd/blob/master/src/dmd/backend/cgxmm.d#L1210 https://github.com/dlang/dmd/blob/master/src/dmd/backend/cgx... And for bug fixes, reference the issue which often gives a detailed explanation for why the code is a certain way: https://github.com/dlang/dmd/blob/master/src/dmd/expressionsem.d#L669 https://github.com/dlang/dmd/blob/master/src/dmd/expressions... Ever since I enhanced the editor I use to open the browser on links, this sort of thing has proven to be very, very handy.
- danuker 5y ago
  Looking at the code on GitHub, this extension may be useful: https://greasyfork.org/en/scripts/2709-linkify-plus https://greasyfork.org/en/scripts/2709-linkify-plus
  - WalterBright 5y ago
    Not needed, I fixed my editor to automagically recognize URLs and make them clickable!
- pm215 5y ago
  I've done the "reference the spec section" thing before -- the difficulty is that often section numbers or similar things get stale when a newer revision of the spec document is published; so it can work for a slow-moving thing like the C spec but is more awkward if the spec/manual gets a revision every six months.
  - WalterBright 5y ago
    It's a good point. This is why for C the references are to a specific standard, i.e. C11. For D, I use named links, which we try to not change. The bugzilla numbers do not change, which is a feature of bugzilla. Even so, the utility of the links far outweighs the possibility of needing to adjust them. P.S. I've found using links to Microsoft documentation to be extremely frustrating, because not only does Microsoft move them around all the time, but will wholesale permanently delete vast swaths of reference material. Notice that the github links are to line numbers. Line numbers are ephemeral, I don't know a way around that.
zelphirkalt 5y ago
With comments it strongly depends on what kind of project your are doing. Is it code which will run in a production environment? What are the capabilities of other other people working on the project? Is it a learning project, in which you soak up every line and explain it for yourself and your future self? Is it your own code, which you are writing? Or is it code you found online and only want to comment? And comment for whom? ... I find especially in learning projects, where I might write some quite dense code, it helps to describe what each line does and answer all the "idiot questions", the ones that you can answer a few minutes later or perhaps hours later with a face palm, when everything is clear again, that arise, when you have to cold boot your brain to pick up the project again or use the code in a real project later on.

rckrd 5y ago

I agree - I think I needed to add a bit more nuance, which I did in https://news.ycombinator.com/item?id=28087165 https://news.ycombinator.com/item?id=28087165

mastersummoner 5y ago
Appreciate the clarification. Comments can (and are) definitely overused and abused, but they absolutely have their place.

rzimmerman 5y ago

Yes I agree with the sentiment, but I think long comments are useful for explaining why a choice was made. Or an idiosyncrasy of the system like you said.

christophergs 5y ago
This. Comments are for why.
- jlc 5y ago
  IMO commit messages are for why.
  - magnusmundus 5y ago
    Do you really prefer digging through years of commit messages to find why a particular line exists? It's a very impractical place for those. And good luck finding the origin of that line if there was an extensive refactor in between. Also, how do you notify a later viewer that there's a "why" they should check? A comment that says "check commit messages for this line"? :) Not to mention: you're losing the notes as soon as you move repositories, or worse, version control systems. Yes, I've hit the "SVN git migrate" wall way too many times. For that reason I even started leaving issue numbers in comments for when it's particularly important, in case we lose the commit<->ticket link down the line.
    - jlc 5y ago
      Typically, it isn't digging. It's the last commit, maybe the one before it, and I have tools for doing this (e.g., magit, fugitive). I don't notify anyone, nor do I need to. When I encounter a WTF moment, I look at the commit messages. When there's nothing there, I curse the last developer. I guess it can be fun spelunking through commit messages, though, to see when the comment was added and if it still applies.
  - FascistDonut 5y ago
    Yeah but you (or another developer) probably won't see the commit message later in the future when you come across that segment of code.
    - andrewnc 5y ago
      I think vs code has an extension that lets you see git info (committer and commit message) inline if you hover over a piece of code.
      - ensiferum 5y ago
        Git lens
  - nradov 5y ago
- cinntaile 5y ago
  Comments being for why or what is not really important imo, having strong feelings about this probably hurts more than it does good. The goal is for someone else (or you) to understand what's going on at a point in the future, you include what is needed to achieve that goal. Whether that's what or why or something else doesn't really matter. Sometimes you don't know how much you have to include, but experience and asking colleagues will help you get a better idea.

deleted 5y ago

[deleted]

gcmeplz 5y ago

Even in situations like that one, I think it's possible to avoid the comment: - setting up a type (with a comment linking to that API's documentation) - setting up a shape validator & a test that asserts that that that field is a string with the correct shape - Using a variable name that makes it clear that something intentional is happening: `const weirdlyStringifiedJSONObject = JSON.stringify(...)` A comment might still be the simplest thing to add, but it doesn't mean it's the only way to document that weirdness. Comments can be fragile compared to the same documentation expressed in code [edit: list formatting]

jjice 5y ago
Those definitely work, but adding a comment is the easiest and clearest way. No need to avoid comments like the plague, just avoid overuse.
d4mi3n 5y ago
I agree that these are all good things, but they cover the what and not the why. I find design documents useful to cover the why--something that results in a long comment in my experience is usually indicative of some non-trivial design decision.

dec0dedab0de 5y ago

By using "should" and "probably" it's acknowledging that there are exceptions. Though I don't think your example is an exception. I would refactor that part out to a seaprate function, and give it a docstring like "json in json, because the api is weird, [link to api docs]." Basically, weird things like that should be refactored into their own spot, instead of called out with a comment in the middle of something else.

deleted 5y ago
[deleted]

5faulker 5y ago

For a larger scale one-man project, you can also use mnemonics to keep track of what code's doing what, but that is unlikely to work out smoothly in a team-work setting.

toolslive 5y ago

sometimes a comment is needed: /* DO NOT DELETE the above test If you're on localhost and opening/closing sockets at high speed, you might end up being connected to yourself by accident. That's what you get when everything is a file and all files are represented with integers */ For example.

taf2 5y ago

10 years later I am very happy when I find I left myself a little note explaining to my future self my thinking at the time… more often then not though I’m left trying to remember those busy days building all the shiny new things

minxomat 5y ago
The only side projects that even have a chance of being rescued from certain death are the ones my past self was kind enough to explain.

zelos 5y ago

Exactly: I think it's almost a rule that you must comment code that does something out of the ordinary for a good reason.

WalterBright 5y ago

I find it very helpful, when implementing part of the compiler, to include a link (for D) or a paragraph number (for C) that references the corresponding specification section: https://github.com/dlang/dmd/blob/master/src/dmd/cparse.d#L591 https://github.com/dlang/dmd/blob/master/src/dmd/cparse.d#L5... Ever since the Intel CPU spec went online, I started doing this with the code generator - providing links to the man page for the instruction being used: https://github.com/dlang/dmd/blob/master/src/dmd/backend/cgxmm.d#L1210 https://github.com/dlang/dmd/blob/master/src/dmd/backend/cgx... And for bug fixes, reference the issue which often gives a detailed explanation for why the code is a certain way: https://github.com/dlang/dmd/blob/master/src/dmd/expressionsem.d#L669 https://github.com/dlang/dmd/blob/master/src/dmd/expressions... Ever since I enhanced the editor I use to open the browser on links, this sort of thing has proven to be very, very handy.

danuker 5y ago
Looking at the code on GitHub, this extension may be useful: https://greasyfork.org/en/scripts/2709-linkify-plus https://greasyfork.org/en/scripts/2709-linkify-plus
- WalterBright 5y ago
  Not needed, I fixed my editor to automagically recognize URLs and make them clickable!
pm215 5y ago
I've done the "reference the spec section" thing before -- the difficulty is that often section numbers or similar things get stale when a newer revision of the spec document is published; so it can work for a slow-moving thing like the C spec but is more awkward if the spec/manual gets a revision every six months.
- WalterBright 5y ago
  It's a good point. This is why for C the references are to a specific standard, i.e. C11. For D, I use named links, which we try to not change. The bugzilla numbers do not change, which is a feature of bugzilla. Even so, the utility of the links far outweighs the possibility of needing to adjust them. P.S. I've found using links to Microsoft documentation to be extremely frustrating, because not only does Microsoft move them around all the time, but will wholesale permanently delete vast swaths of reference material. Notice that the github links are to line numbers. Line numbers are ephemeral, I don't know a way around that.

zelphirkalt 5y ago

With comments it strongly depends on what kind of project your are doing. Is it code which will run in a production environment? What are the capabilities of other other people working on the project? Is it a learning project, in which you soak up every line and explain it for yourself and your future self? Is it your own code, which you are writing? Or is it code you found online and only want to comment? And comment for whom? ... I find especially in learning projects, where I might write some quite dense code, it helps to describe what each line does and answer all the "idiot questions", the ones that you can answer a few minutes later or perhaps hours later with a face palm, when everything is clear again, that arise, when you have to cold boot your brain to pick up the project again or use the code in a real project later on.