I've never seen a language's style guide recommend avoiding comments before
1–10 of 198 posts
Re: I've never seen a language's style guide recommend avoiding comments before
#2I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code.
One of the best cases for comments IMO is documenting an unexpected behaviour on the part of a third-party API. But even then, correct exception / error-handling code can obviate the need for comments in many cases.
If I'm reading code (from an experienced programmer) and I see a comment, I immediately pay attention, because Here Be Dragons.
Re: I've never seen a language's style guide recommend avoiding comments before
#3I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code. One of the best cases for comments IMO is documenting an unexpected behaviour on the part of a third-party API. But even then, correct exception / error-handling code can obviate the need for comments in many cases. If I'm reading code (from an experienced programmer) an…
The situation must be differentiated by language/environment. The suggestions for Haskell are certainly not bad. They hold, too, for many systems programming.
For scientific coding, comments should align with the underlying theory for the code: “This implements matrix transposition with regard to ... as defined by ...”, so that next generations can align code with papers better.
And when you’re in a wacky environment like the PHP runtime or coding for a moving target like the browser, comments might be indispensable to explain one or the other really strange way of doing things, where you simply have no other choice. Look at the [jQuery source code](https://github.com/jquery/jquery/tree/master/src), where they comment excessively, which browser quirk they address with which work-around.
Re: I've never seen a language's style guide recommend avoiding comments before
#4I agree. Comments sometimes make it difficult to go through the source code. That's why I always loved Java naming convention that suggests variables and method names to be self-explanatory.
Re: I've never seen a language's style guide recommend avoiding comments before
#5> I repeat: Try hard - very hard - preferably repeatedly - to remove unexpected behaviour from your program. Comments can never fix unexpected behaviour.
This is golden!
Re: I've never seen a language's style guide recommend avoiding comments before
#6The article correctly advices against commenting the obvious. I think it is often practice by novice programmers to assure themselves about what the language expression actually does.
What the article omits is the suggestion of commenting the right way, i.e. adding reasoning or the description of the high level logic behind the code.
Re: I've never seen a language's style guide recommend avoiding comments before
#7Comment only magical code, but don't write magical code.
Re: I've never seen a language's style guide recommend avoiding comments before
#8The article is spot on. Comment as last resort.
Re: I've never seen a language's style guide recommend avoiding comments before
#9The article correctly advices against commenting the obvious. I think it is often practice by novice programmers to assure themselves about what the language expression actually does. What the article omits is the suggestion of commenting the right way, i.e. adding reasoning or the description of the high level logic behind the code.
Yes, obviously the examples given in the link are bad style of comments. But sometimes you need to explain the reasons behind the (Haskell) equations, just like one would do in a Math paper. So there's a use case for the literate Haskell files *.lhs (http://www.haskell.org/haskellwiki/Literate_programming).
Re: I've never seen a language's style guide recommend avoiding comments before
#10I was always told that if someone couldn't tell what your code was doing by glancing at it, you'd done it wrong and should re-write it.
I know that's absurd in practice, we don't always have the time but I've always used comments as a last resort.
If I need to comment code to make it understandable at a glance, so be it but I'd rather avoid them all together and rewrite until it's clear enough without them.