News for hackers. Stuff that matters.
Re:Avoid Else, Return Early (2013) by titzer on Monday March 26, 2018 @09:35AM (#16678707)
> Comments are not documentation.

Probably overly generalized to be pithy, but no.

Comments are by very definition documentation, which can and should cover of all of the what/why/who/how/where.

Documentation that occasionally explains how to use code can actually be useful!

Unless you actually get around to writing a user manual (which gets out of date), please do consider documenting how something should be used, particularly in libraries.

Re:Avoid Else, Return Early (2013) by Mithaldu on Monday March 26, 2018 @09:39AM (#16678741)
As a Perl developer i mean this literally and transfer it to other languages as well. POD (or a block comment above a function) describes the API and use cases of the function. Inline comments inside the function exist only to provide explanation for the next maintainer when they see a strange construct. Any other type of comment needs to be refactored.

Also, i never said documentation isn't useful. HOW and WHY are useful. WHAT in documentation and comments isn't because it should be in the variable/function/method/class/instance name.

(Who/Where/When are covered by the source repository and the blame function.)