It's doesn't recommend avoiding comments - it encourages to write understandable code and avoid meaningless comments. It is a basic rule of the clean code.
I've never seen a language's style guide recommend avoiding comments before
31–40 of 198 posts
Re: I've never seen a language's style guide recommend avoiding comments before
#32Comments say what your code does, your code says how you do it. The swap example is trivial, but for most functions it is good to add an API comment, because how you use the function shouldn't depend on how it's implemented, but what it should do, described in the comment. That way you can change your implementation as long as you don't change the contract. In other words, changing how your code does something should…
[deleted]
Re: I've never seen a language's style guide recommend avoiding comments before
#33I 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.
I disagree with that sentiment.
Using Python or Perl it is easy to go from a for loop to a map or list comprehension. For many less experienced programmers it will make it less readable and more difficult to comprehend. Using a more functional approach will usually lead to less side effects and silly bugs, so I prefer to code this way, and add a comment to explain what the line is doing if it is not obvious.
Re: I've never seen a language's style guide recommend avoiding comments before
#34Good code should be self documenting.
Re: I've never seen a language's style guide recommend avoiding comments before
#35I've seen this many times:
...thus they (comments) tend to diverge from actual implementation.
Re: I've never seen a language's style guide recommend avoiding comments before
#36This 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.
The argument is not to never use comments, but rather to avoid bad comments.
I realize this, but the article doesn't provide any clear definition of what actually is a bad comment. It only gives trivial examples of bad comments such as "increment a by one".
Since I don't think anyone here would argue that "increment a by one" is a useful comment, the part about duplicate/obvious comments isn't adding much to the discussion about the usefulness of comments.
Nevertheless, it's true that comments cannot be checked by the compiler, and that's a more interesting point, I think.
Re: I've never seen a language's style guide recommend avoiding comments before
#37It's often a good idea to comment "why" the code exist, if it is non-obvious (e.g. it's obvious to sanitize input parameters). The comment must be short and possibly point to a ticket wrote somewhere else.
It may be a good idea to comment "what" the code does, if it isn't clear (the code itself is "how" it is done, but "what" does it do may be hard to read, e.g. sometimes you use a clever hack for performance reasons).
As always, handle with care :-)
Re: I've never seen a language's style guide recommend avoiding comments before
#38Personally 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!
Re: I've never seen a language's style guide recommend avoiding comments before
#39Write comments that explain why a certain line is there.
Let's say you are parsing a standard tab delimited file. You find that the tab delimited file has some non-standard features, so you have to write some extra lines of code to handle it. For people who thinks the code just parses a standard tab delimited file, these lines will be confusing, so you comment these lines and say why you included them.
Re: I've never seen a language's style guide recommend avoiding comments before
#40Comments aren't necessary at all. If the code was difficult to write, it should be difficult to read. :-P