The stablished policy is: "don't use comments to replace proper names and abstractions".
I wrote more about this here (it's Lua code, but it applies to any language):
http://kiki.to/blog/2012/03/16/small-functions-are-good-for-...
I've never seen a language's style guide recommend avoiding comments before
41–50 of 198 posts
Re: I've never seen a language's style guide recommend avoiding comments before
#42Personally I have no problems with comments in code for complex functions etc. But pointless comments like this below drives me insane. // get the user $user = $this->getUser(); Times that by the thousands of lines in a project and you have one big headache!
> Personally I have no problems with comments in code for complex functions etc
I hope you have a problem with complex functions. (They should be made as simple as possible).
Re: I've never seen a language's style guide recommend avoiding comments before
#43Hmm. This is just one guy's style guide on the public wiki.
http://www.haskell.org/haskellwiki/index.php?title=Commentin...
It isn't official in any sense.
Re: I've never seen a language's style guide recommend avoiding comments before
#44I'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?
No comments are better than bad comments. There is nothing worse than a misleading description.
Re: I've never seen a language's style guide recommend avoiding comments before
#45Personally I have no problems with comments in code for complex functions etc. But pointless comments like this below drives me insane. // get the user $user = $this->getUser(); Times that by the thousands of lines in a project and you have one big headache!
> Personally I have no problems with comments in code for complex functions etc I hope you have a problem with complex functions. (They should be made as simple as possible).
[deleted]
Re: I've never seen a language's style guide recommend avoiding comments before
#46Personally I have no problems with comments in code for complex functions etc. But pointless comments like this below drives me insane. // get the user $user = $this->getUser(); Times that by the thousands of lines in a project and you have one big headache!
> Personally I have no problems with comments in code for complex functions etc I hope you have a problem with complex functions. (They should be made as simple as possible).
Why fear complexity when its the only way to get something done, other than not doing it?
Re: I've never seen a language's style guide recommend avoiding comments before
#47This is not convincing to me because the examples are trivial: -- swap the elements of a pair swap :: (a,b) -> (b,a) Yes this is redundant. let b=a+1 -- add one to 'a' Yes this is also redundant Does it mean that every piece of code can be expressed as clearly as in a one-line comment in natural language? I don't think so.
But you see, nobody on the internet has ever offered up examples of good comments before, at least that I can find. So if you say these comments are bad, but there exists good comments, why not provide examples of good comments to make your argument stronger?
Re: I've never seen a language's style guide recommend avoiding comments before
#48Good code should be self documenting.
> Good code should be self documenting.
Good code needs no test either,... wait no ,that's a stupid thing to say,because nobody writes "good code",code isnt good or bad,it either results in the expected behavior or not.
Re: I've never seen a language's style guide recommend avoiding comments before
#49Similar thoughts were seen in the SICP book.
"In this book we don't use many comments; we try to make our programs self-documenting by using descriptive names."
http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-15.html...
Re: I've never seen a language's style guide recommend avoiding comments before
#50I'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?
No comments are better than bad comments. There is nothing worse than a misleading description.
I've always gone with the adage: if the comment and code do not agree, don't assume that either of them are correct.
A bad description isn't just a problem in itself, it can indicate a worse problem sat waiting to jump out and bite as you walk by.