Live data from Hacker News

I've never seen a language's style guide recommend avoiding comments before

haskell.org

61–70 of 198 posts

Re: I've never seen a language's style guide recommend avoiding comments before

#61
Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on.

Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years later, figure out what the heck your original intent was or why a block of code exists at all.

As I get older, I find it helps me remember what I was doing.

One of my software developer friends was fond of saying: "the worst code I ever saw was my own!"

YES if your code is clean and elegant and well named and clear you don't need to explain anything in common language.

YES you should strive for such.

However, the REALITY is your code sucks and no one is going to want to have to figure out what the heck you were doing. A few comments would really help.

The next reality is that the typical developer may be literate in a dozen or more languages and the language du jour that you coded so elegantly in has fallen out of favor and no one remembers those dusty corners you so beautifully exploited to make something work.

Comments would help even more if you learn to use some basic grammar and spelling when you create your comments. (It doesn't have to be literature, but try to make your comments as readable as you think your code is - please!) Nothing will turn another developer off to trying to decipher your code than a few comments that make you look like a moron.

Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.

Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.

Re: I've never seen a language's style guide recommend avoiding comments before

#62
Comments I liked to write were when I found successive optimizations (lots of symmetries in the algorithm) leading to very short code. Almost too factored to be understood easily so I added a comment wall above telling the steps I went through before hitting the final code below.

Re: I've never seen a language's style guide recommend avoiding comments before

#63
post #61

Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…

> Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.

Whatever their benefits are, this is not true at all. Comments are expensive to write and maintain. They are VERY VERY expensive to maintain because there is no automated way to test them.

Re: I've never seen a language's style guide recommend avoiding comments before

#64
post #61

Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…

Hahah, I so much agree!

I also think you should target for 0 comments in an ideal world. Every time I write a comment I remind myself, can't you really write this in a more obvious way?

But reality is that exercise requires time that you don't always have

Re: I've never seen a language's style guide recommend avoiding comments before

#66
post #61

Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…

I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.

Re: I've never seen a language's style guide recommend avoiding comments before

#67
post #29

Avoiding comments that do what your code should be doing is common practice, and I think that's what this style guide is recommending. Comments are useful to describe __why__ you're doing something, often when you are not able to change the unexpected behaviour. Whenever I build an API library, my code is littered with comments like "Acme Corp API requires this happens before that" with a link to that bit of the API…

Completely agree :) In some cases I prefer to wrap it in an aptly named function, but in other cases I prefer the whole algorithm to be in a single function, making comments a very useful tool for "naming".

Re: I've never seen a language's style guide recommend avoiding comments before

#69

I've seen this many times: ...thus they (comments) tend to diverge from actual implementation. It happens, you update/refactor code, and forget to update the comments. Thus the comments are outdated or worse not applicable anymore. Common mistake by less-detailed oriented developers. Begs the question, in this case is is better to have confusing/incorrect comments, or no comments at all?

" ...thus they (comments) tend to diverge from actual implementation."

In my experience comments are no more likely to diverge than tests are. With tests you have the advantage that they must compile. With comments you have the advantage that they are inline/interspersed with your code and so get read every time the code is read.

"It happens, you update/refactor code, and forget to update the comments."

So then the next developer to read that part of the code notices that the comment doesn't make sense, or is not well written, and they update it. No different than if they notice poorly named/misleading functions or variable names or a dozen other code smells. No big deal and certainly not a good case for commenting less.

Re: I've never seen a language's style guide recommend avoiding comments before

#70
post #61

Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…

Agree perfectly. "Your code should be self-documenting" is one of the memes that give you an excuse for being lazy. While true in the ideal case, very few programmers are able to (or even in a domain where it is possible to) write code that documents itself.
Post reply on HN