News for hackers. Stuff that matters.
Re:Golden rules for becoming a better programmer by jlg23 on Tuesday January 26, 2016 @06:26PM (#10977057)
11. Know when to break any of the first 10 rules.

12. Never listen to anybody who tells you "You shouldn't need comments if your code is clear enough to read." - the next one reading your code (probably you, 10 years later) will love you for documenting the WHY just as much as s/he'll hate you for having to rely on documentation that explains the WHAT.

Re:Golden rules for becoming a better programmer by MaybiusStrip on Tuesday January 26, 2016 @09:09PM (#10977754)
I like how Robert C. Martin puts it: before you write a comment, ask yourself whether you can write the code in a way that makes the comment unnecessary. If you cannot, then it is better to leave the comment than none at all.
Re:Golden rules for becoming a better programmer by mannykannot on Tuesday January 26, 2016 @11:08PM (#10978139)
Fair enough, so long as you understand that programming languages are not expressive enough, in general, to clearly explain purpose and rationale. In these matters, providing a hint through identifier naming is not an adequate substitute for a clear explanation in a human language.
Re:Golden rules for becoming a better programmer by roddux on Wednesday January 27, 2016 @06:08AM (#10979437)
As an aside, clearly written code does a pretty good job of explaining what it does, but not why. Sometimes there will have been reasons for avoiding a particular method, which isn't made obvious by the code itself.
Re:Golden rules for becoming a better programmer by imron on Wednesday January 27, 2016 @12:22AM (#10978390)
However 10 years later, it is also likely you'll be reading the comments for the explanation and realise that what the comments say is different from what the code does (because over the span of 10 years the code was updated but not the comments) and that's just as confusing.

If the code is written with meaningful variable and function names, and functions no larger than a screen, then lack of comments isn't really a problem.

Re:Golden rules for becoming a better programmer by yoklov on Wednesday January 27, 2016 @02:36AM (#10978789)
Yep, and often the code that breaks what the comment says is far away. Too easy to change something that subtly invalidates a comment in some other module. Especially if you didn't write that module.
Re:Golden rules for becoming a better programmer by mannykannot on Wednesday January 27, 2016 @08:15AM (#10979835)
It is also possible that your change subtly invalidates the semantics implied by the identifiers used in some other module. In either case, there is a nontrivial possibility that you have introduced a bug (and quite possibly a subtle one).
Re:Golden rules for becoming a better programmer by mannykannot on Wednesday January 27, 2016 @08:08AM (#10979799)
Variable and function names can be just as misleading as comments. I am not aware of any language which guarantees the semantics implied by your choice of identifiers.
Re:Golden rules for becoming a better programmer by eCa on Tuesday January 26, 2016 @07:04PM (#10977250)
I agree, but:

"reduces the need for comments" != "shouldn't need comments"

Re:Golden rules for becoming a better programmer by piess on Tuesday January 26, 2016 @07:14PM (#10977300)
Well said
Re:Golden rules for becoming a better programmer by mywittyname on Wednesday January 27, 2016 @10:01AM (#10980296)
> will love you for documenting the WHY just as much as s/he'll hate you for having to rely on documentation that explains the WHAT.

I've saved myself so many times with this. External services are bad about having odd-ball edge-case errors that require a little funny business on your end in order to keep operational. So there are often little code snippets that look like their bugs, but are actually necessary to prevent regressions. Without a comment as to why the code is there, some boy scout is going to "fix" it (and the now failing unit test) and introduce a regression.

Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @04:08PM (#10983375)
Anyone that breaks code and then doesn't investigate why a unit test exists is not a boy scout, but a vandal.
Re:Golden rules for becoming a better programmer by mark-r on Tuesday January 26, 2016 @11:13PM (#10978167)
I was going to say that, glad someone beat me to it. No matter how clear your code is, it can't explain the WHY.
Re:Golden rules for becoming a better programmer by ap22213 on Tuesday January 26, 2016 @08:34PM (#10977624)
Don't they teach kids how to read code these days?