> On 22 Mar 2018, at 01:27, Larry McVoy <lm@mcvoy.com> wrote:
>
>> On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote:
>> They also state: "Comments are meant to help the reader of a program.  They
>> do not help by saying things the code already plainly says, or by
>> contradicting the code, or by distracting the reader with elaborate
>> typographical displays.  The best comments aid the understanding of a
>> program by briefly pointing out salient details or by providing a
>> larger-scale view of the proceedings."
>
> I so agree with this.  Verbose comments suck.  Too many comments suck.
> Why?  Because the code evolves and it's work to evolve the comments
> as well.  Too many comments means they are not maintained and they
> become incorrect.
>
> I *HATE* comments that are not correct, hate that so much that if you did
> that we would talk, if you kept doing that, you are fired.  No comments
> are MUCH better than incorrect comments.
>
> Terseness in comments is good.  Comment where it is not obvious what
> is going on.  And maintain the comments like you maintain the code.
>
> I agree with Dan (I think) that coding is still a craft and getting the
> comments right is one of the hardest things to master (and I agree that
> Unix did it pretty darn well).  No comments suck, too much sucks, just
> right is so darn pleasant.
>
> --lm

on the commenting subject, and as it was Shannon’s anniversary recently... i always felt information theory relates well to comments.

i.e. repeating anything i can see from the code (like “returns void”) tells me nothing.

telling me something non-obvious (“allocate one more for end of list sentinel”)  really helps.

-Steve