From mboxrd@z Thu Jan  1 00:00:00 1970
From: steve@quintile.net (Steve Simon)
Date: Thu, 22 Mar 2018 14:46:13 +0000
Subject: [TUHS] Comments in early Unix systems
In-Reply-To: <20180322012720.GN9739@mcvoy.com>
References: <20180321141753.25C4418C088@mercury.lcs.mit.edu>
 <CAC20D2M6x5wn5_=HDWYsZyBqu_Ba58-oQ8Ca53XBmaRjS62=6Q@mail.gmail.com>
 <6c6699c0-15db-604a-181c-7dad282599e1@kilonet.net>
 <CABH=_VREt+Ay+T3wnGKvGyKn-7W7dn6K4vT7huBmX4a4GzjQKg@mail.gmail.com>
 <CAEoi9W6_-2HLs=ywM42OtOG00GeBd=c0odxXhtsDcZhKy-n4Ew@mail.gmail.com>
 <CAC20D2ORh+k9cBF1DgZ=A86YkrWKPtiNYzO=7MLz-=SNDTPEew@mail.gmail.com>
 <CABH=_VT+Pu=xZ=vk30Z3JrZN0cf=BG6hg7x++FTnb4iptzbNMw@mail.gmail.com>
 <20180321202810.GA6280@minnie.tuhs.org>
 <CALMnNGhD_3CbGaKx0_U0Hcbjq0E6Edecs39F0ZuWH-xys8gAcQ@mail.gmail.com>
 <20180322012720.GN9739@mcvoy.com>
Message-ID: <F86441D1-FB0C-41D9-8519-E31F3238A235@quintile.net>



> On 22 Mar 2018, at 01:27, Larry McVoy <lm at 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