[TUHS] Comments in early Unix systems

Bakul Shah bakul at bitblocks.com
Thu Mar 22 11:59:33 AEST 2018


On Mar 21, 2018, at 6:27 PM, 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.

When reading new code, I initially ignore comments,
at least within a function, and just try to figure
out what the code does. This is because often people
do not update comments. Code has to at least compile
so they are forced to update it and hopefully test
it but comments....

In the Go language ecosystem they have "go doc" which
can pull out comments at different level. Example:

go doc io // package level + top level exported declarations
go doc io.Copy // function level comments + header
go doc io.Reader // interface level + interface body

and so on. This does incentivize people to write good
comments.  This is very handy in that you can see how
your comments read when divorced from the code. But
notice that no comments within a function are output.
[Perhaps IDEs show relevant comments too but I find
them too heavyweight and don't use them]

A larger point is appropriate documentation, not just
source comments. There should be a function spec as
well. I used to write a manpage for a command etc.
first, especially when someone else has to code it.
A manpage is describes the syntax, function, results
and errors and links to related manpages. All this
usually in a page or two!




More information about the TUHS mailing list