5 ms·

100%. It's amazing how many GitHub repos have little to no comments, not even file or function overview comments. The amount of time save by potential contribut

by jjice 7y ago

100%. It's amazing how many GitHub repos have little to no comments, not even file or function overview comments. The amount of time save by potential contributors reading and having to interpret the code is way longer than it would take for the author to write the comments in the first place. To each their own, but comments are generally a positive addition to code.

CmdrKrool 7y ago
Yes, the greatest value add of comments for me is the potential time-saving, in the ideal case (re)acquainting you with a large work of code by guiding your attention from the top-down - firstly to orient you in the broad structural aspects, then to fly you smoothly down towards the minutae of reading individual lines of code. This does sometimes entail a few 'what'-style comments, so I'm disappointed to regularly read of programmers that have apparently taken up arms against them.
- t-writescode 7y ago
  Are they ‘what?’ or ‘wat?’ comments? Maybe that’s the difference?
  - whynaut 7y ago
    what, opposed to ‘why’ or ‘how’
    - t-writescode 7y ago
      No, I understand that part; but, I think of a "what" comment as "incrementing value of X" a "wat" comment, like the meme, is more of a "this is a really weird blob of code that might be obvious when you break the whole thing apart; but, what it's doing is _this_ this is the implementation of it because we have a complicated data structure that's connecting all these pieces"
woah 7y ago
I find it's not useful to have comments in code that you are actively working on since they quickly get out of date. They are best added when one finishes work on a block of code.
- jannotti 7y ago
  I get the feeling, but I rarely think "I'm completely done now, time to comment!" Better to admit that and document a bit earlier than when it's "finished".
  - lanstin 7y ago
    More accurate comments that way, isn't it. Nothing sadder than the optimistic comment from before implementation, which took the regular twisty path towards correctness in the corner cases. More of a risk for the higher level methods than the little "DRY" functions that do something relatively functional.
  - miketuritzin 7y ago
    I frequently think just before committing/pushing, "Time to add some comments!" That doesn't mean the code is fully finished, but it does provide a clear point in time to add them (when needed).
- hermitdev 7y ago
  At a previous job, when I transitioned off a few projects that I had solely worked on for 7 years, I warned the dev taking over from me: I don't usually comment my code, but when I do, you'd better pay attention. I think in one of them, only a single source file (C++) had comments, and there were more comments than code. I was explaining an intricate locking pattern around a data cache. Like you suggested, I added the comments after I'd done the work because it was a work in progress. I added the comments because it was a very fragile piece of code and sensitive to changes (e.g. really easy to cause a deadlock or race condition if changed).
- 6510 7y ago
  While working on it my comment explains what the block should be doing. Extra points for lists of harebrained ideas that will likely never happen.
BurningFrog 7y ago
I think there are levels: Level 1: Garbage code with no or bad comment. Level 2: Garbage code with good comments. Level 3: Good code with comments Level 4: Code good enough that it doesn't need comments, with rare exceptions. Each level is better than the previous. You can't level up directly from 1 to 4. Still, 4 is the best level. I know it sounds weird if you haven't seen it.
- zadler 7y ago
  I still think a file should have at least some small comment at the top to help orient the reader and set expectations.
- Sevaris 7y ago
  I don't think level 4 exists. There is no code for problems of sufficient complexity that are self-explanatory. There are too many hidden assumptions and foreknowledge and tradeoffs and decisions baked into a block of code that, unless it's trivial, there's no way code itself can reflect it adequately.
  - jbotz 7y ago
    It does exist, but only for snippets, sections of code, or at best whole individual functions, especially in languages that are concise and expressive (which are most languages that are not Java ;-). But even really good code still needs comments about how things fit together, what to find where, etc., because those things are generally not expressible in programming languages, although a good module system can help a lot with that.
  - BurningFrog 7y ago
    I have three things to say about that: 1. I did allow for "rare exceptions". Some things do need to be explained outside of the code. Maybe we're not so different after all :) 2. There are a number of techniques to write such code. Before I learned them, I had NO IDEA. One is to take what would have been comments and use them as variable or function names. This includes (and I had real resistance before I accepted this) breaking out a variable of function only in order to give it an informative name. "Level 4" doesn't just happen. You work at it for a long time and sharpen your skills in that area. 3. To me, much of the art of writing software is to find ways to divide a complex problem into simple pieces. If my code is real complex, I look for simpler way to write it. And I look hard.

by jjice 7y ago

CmdrKrool 7y ago

Yes, the greatest value add of comments for me is the potential time-saving, in the ideal case (re)acquainting you with a large work of code by guiding your attention from the top-down - firstly to orient you in the broad structural aspects, then to fly you smoothly down towards the minutae of reading individual lines of code. This does sometimes entail a few 'what'-style comments, so I'm disappointed to regularly read of programmers that have apparently taken up arms against them.

t-writescode 7y ago
Are they ‘what?’ or ‘wat?’ comments? Maybe that’s the difference?
- whynaut 7y ago
  what, opposed to ‘why’ or ‘how’
  - t-writescode 7y ago
    No, I understand that part; but, I think of a "what" comment as "incrementing value of X" a "wat" comment, like the meme, is more of a "this is a really weird blob of code that might be obvious when you break the whole thing apart; but, what it's doing is _this_ this is the implementation of it because we have a complicated data structure that's connecting all these pieces"

woah 7y ago

I find it's not useful to have comments in code that you are actively working on since they quickly get out of date. They are best added when one finishes work on a block of code.

jannotti 7y ago
I get the feeling, but I rarely think "I'm completely done now, time to comment!" Better to admit that and document a bit earlier than when it's "finished".
- lanstin 7y ago
  More accurate comments that way, isn't it. Nothing sadder than the optimistic comment from before implementation, which took the regular twisty path towards correctness in the corner cases. More of a risk for the higher level methods than the little "DRY" functions that do something relatively functional.
- miketuritzin 7y ago
  I frequently think just before committing/pushing, "Time to add some comments!" That doesn't mean the code is fully finished, but it does provide a clear point in time to add them (when needed).
hermitdev 7y ago
At a previous job, when I transitioned off a few projects that I had solely worked on for 7 years, I warned the dev taking over from me: I don't usually comment my code, but when I do, you'd better pay attention. I think in one of them, only a single source file (C++) had comments, and there were more comments than code. I was explaining an intricate locking pattern around a data cache. Like you suggested, I added the comments after I'd done the work because it was a work in progress. I added the comments because it was a very fragile piece of code and sensitive to changes (e.g. really easy to cause a deadlock or race condition if changed).
6510 7y ago
While working on it my comment explains what the block should be doing. Extra points for lists of harebrained ideas that will likely never happen.

BurningFrog 7y ago

I think there are levels: Level 1: Garbage code with no or bad comment. Level 2: Garbage code with good comments. Level 3: Good code with comments Level 4: Code good enough that it doesn't need comments, with rare exceptions. Each level is better than the previous. You can't level up directly from 1 to 4. Still, 4 is the best level. I know it sounds weird if you haven't seen it.

zadler 7y ago
I still think a file should have at least some small comment at the top to help orient the reader and set expectations.
Sevaris 7y ago
I don't think level 4 exists. There is no code for problems of sufficient complexity that are self-explanatory. There are too many hidden assumptions and foreknowledge and tradeoffs and decisions baked into a block of code that, unless it's trivial, there's no way code itself can reflect it adequately.
- jbotz 7y ago
  It does exist, but only for snippets, sections of code, or at best whole individual functions, especially in languages that are concise and expressive (which are most languages that are not Java ;-). But even really good code still needs comments about how things fit together, what to find where, etc., because those things are generally not expressible in programming languages, although a good module system can help a lot with that.
- BurningFrog 7y ago
  I have three things to say about that: 1. I did allow for "rare exceptions". Some things do need to be explained outside of the code. Maybe we're not so different after all :) 2. There are a number of techniques to write such code. Before I learned them, I had NO IDEA. One is to take what would have been comments and use them as variable or function names. This includes (and I had real resistance before I accepted this) breaking out a variable of function only in order to give it an informative name. "Level 4" doesn't just happen. You work at it for a long time and sharpen your skills in that area. 3. To me, much of the art of writing software is to find ways to divide a complex problem into simple pieces. If my code is real complex, I look for simpler way to write it. And I look hard.