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

Re:I've never seen a language's style guide recommend avoidi... by MerreM on Wednesday July 23, 2014 @04:53AM (#8073411)

I 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.

[ Parent | on HN ]

Re:I've never seen a language's style guide recommend avoidi... by collyw on Wednesday July 23, 2014 @05:40AM (#8073506)

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.

[ Parent | on HN ]

Re:I've never seen a language's style guide recommend avoidi... by spacemanmatt on Wednesday July 23, 2014 @06:33AM (#8073614)

I want comments to give me a short-cut to reading a long block of code, and I want comments to give me a basic method of analyzing the code for correctness. The thumb-rule of documenting "why" rather than "how" seems to apply.

I shouldn't have to read code in detail to understand it, unless it is broken and I am fixing it. Comments should inform me on the broad strokes of the code.

[ Parent | on HN ]