6 ms·

> ... not so good code: if it was, we wouldn’t need a comment... How much longer will this rumor persist that "good code" doesn't need commenting? Good comment

> ... not so good code: if it was, we wouldn’t need a comment... How much longer will this rumor persist that "good code" doesn't need commenting? Good comments explain things that aren't immediately obvious from the code.

CraigJPerry 7y ago
Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination of code and configuration / metadata. So that leaves the “why”. To my mind, code comments are the worst place to record why a particular implementation exists. The why often needs collaboration with non-coders.
- artsyca 7y ago
  It's definitely the why for any particular unorthodox bits like shims hacks workarounds and the like The worst is finding some snippet from stack overflow or GitHub without a reference to the issue to back up why this thing is here or perhaps a TODO: with an improvement
- minaa-chan 7y ago
  I disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true. Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.
  - CraigJPerry 7y ago
    The comments are very often not true, that's why there's so much push back
    - minaa-chan 7y ago
      So they should be updated the same as any other documentation. They're there to help. They don't need to be 100% infallible to be useful.
clarry 7y ago
Most code should be boring and immediately obvious. I don't run into lots of real world code that needs much explaining. Sometimes you do something weird or not-obvious for good reason, but I see plenty of comments explaining things that only need to be explained due to poor design. Also poor comments that don't really explain anything that isn't obvious by looking.
- classified 7y ago
  I'm not sure whether I should envy or pity you. Writing code that is that obvious and boring cannot be very fulfilling. How long until a machine does that for you (after all, automating boring and obvious stuff is what we programmers do)? OTOH, on days where I feel lazy I can only wish my world were that simple.
  - gobayesgo 7y ago
    Any monkey can puke thousands of lines of code. Producing code so boring that fellow humans can understand it immediately is the real challenge in programming. It requires much more effort and care than blaming everyone else for not understanding a sophisticated pile of mess.
- AstralStorm 7y ago
  The code might be obvious, but if you don't include the reason why it exists it's a target for removal. And having too many of those makes either for garbage or hard decisions when refactoring. Writing the rationale is the most important comment you must not skip. And there would be links to design documentation so that it can be kept up to date. (For non-programmers.)
  - swish_bob 7y ago
    Why it exists ought to be explained by the existence of a test. This isn't always possible, but it's far more possible than many developers seem to think.
    - 7y ago
artsyca 7y ago
A rule of thumb I follow is that code is twice as hard to read as it is to write so comments may of course help but in the other case comments that have to overly explain what the code is doing or why it's doing it also indicate that the code ought to be revised My process of writing code is to of course code a proof of concept in order to get a feel for the problem domain this could be considered a spike in agile parlance Then the primary and alternate flows can be coded against a basic test suite followed by a refactor and then a comments pass Depending on what comments arise perhaps another refactor may be in order I typically try to follow the spirit of TRUE software
deleted 7y ago
[deleted]
goto11 7y ago
Maybe because some people have learnt they should comment but haven't learnt how to comment properly. And as often the case in this industry, the fact that some people do some thing badly leads other people to forbid the thing altogether.
Izkata 7y ago
You left out the most important part of this criticism: > ...to explain each line of code. Commenting every line is a hint to a more pervasive problem. This section has nothing to do with "comments are bad".
BitwiseFool 7y ago
We typically use comments to describe our client's business process. Even though the code itself looks straightforward what the client wants certainly isn't.
blakehaswell 7y ago
> How much longer will this rumor persist that "good code" doesn't need commenting? Indeed. I recently came across an article[0] which does a good job of debunking this idea, and describing different types of comments and when they can be valuable. Have a read if you're skeptical about comments. [0] http://antirez.com/news/124 http://antirez.com/news/124

CraigJPerry 7y ago

Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination of code and configuration / metadata. So that leaves the “why”. To my mind, code comments are the worst place to record why a particular implementation exists. The why often needs collaboration with non-coders.

artsyca 7y ago
It's definitely the why for any particular unorthodox bits like shims hacks workarounds and the like The worst is finding some snippet from stack overflow or GitHub without a reference to the issue to back up why this thing is here or perhaps a TODO: with an improvement
minaa-chan 7y ago
I disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true. Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.
- CraigJPerry 7y ago
  The comments are very often not true, that's why there's so much push back
  - minaa-chan 7y ago
    So they should be updated the same as any other documentation. They're there to help. They don't need to be 100% infallible to be useful.

clarry 7y ago

Most code should be boring and immediately obvious. I don't run into lots of real world code that needs much explaining. Sometimes you do something weird or not-obvious for good reason, but I see plenty of comments explaining things that only need to be explained due to poor design. Also poor comments that don't really explain anything that isn't obvious by looking.

classified 7y ago
I'm not sure whether I should envy or pity you. Writing code that is that obvious and boring cannot be very fulfilling. How long until a machine does that for you (after all, automating boring and obvious stuff is what we programmers do)? OTOH, on days where I feel lazy I can only wish my world were that simple.
- gobayesgo 7y ago
  Any monkey can puke thousands of lines of code. Producing code so boring that fellow humans can understand it immediately is the real challenge in programming. It requires much more effort and care than blaming everyone else for not understanding a sophisticated pile of mess.
AstralStorm 7y ago
The code might be obvious, but if you don't include the reason why it exists it's a target for removal. And having too many of those makes either for garbage or hard decisions when refactoring. Writing the rationale is the most important comment you must not skip. And there would be links to design documentation so that it can be kept up to date. (For non-programmers.)
- swish_bob 7y ago
  Why it exists ought to be explained by the existence of a test. This isn't always possible, but it's far more possible than many developers seem to think.
  - 7y ago

artsyca 7y ago

A rule of thumb I follow is that code is twice as hard to read as it is to write so comments may of course help but in the other case comments that have to overly explain what the code is doing or why it's doing it also indicate that the code ought to be revised My process of writing code is to of course code a proof of concept in order to get a feel for the problem domain this could be considered a spike in agile parlance Then the primary and alternate flows can be coded against a basic test suite followed by a refactor and then a comments pass Depending on what comments arise perhaps another refactor may be in order I typically try to follow the spirit of TRUE software

deleted 7y ago

[deleted]

goto11 7y ago

Maybe because some people have learnt they should comment but haven't learnt how to comment properly. And as often the case in this industry, the fact that some people do some thing badly leads other people to forbid the thing altogether.

Izkata 7y ago

You left out the most important part of this criticism: > ...to explain each line of code. Commenting every line is a hint to a more pervasive problem. This section has nothing to do with "comments are bad".

BitwiseFool 7y ago

We typically use comments to describe our client's business process. Even though the code itself looks straightforward what the client wants certainly isn't.

blakehaswell 7y ago

> How much longer will this rumor persist that "good code" doesn't need commenting? Indeed. I recently came across an article[0] which does a good job of debunking this idea, and describing different types of comments and when they can be valuable. Have a read if you're skeptical about comments. [0] http://antirez.com/news/124 http://antirez.com/news/124