From mboxrd@z Thu Jan 1 00:00:00 1970 From: lm@mcvoy.com (Larry McVoy) Date: Wed, 21 Mar 2018 18:27:20 -0700 Subject: [TUHS] Comments in early Unix systems In-Reply-To: References: <20180321141753.25C4418C088@mercury.lcs.mit.edu> <6c6699c0-15db-604a-181c-7dad282599e1@kilonet.net> <20180321202810.GA6280@minnie.tuhs.org> Message-ID: <20180322012720.GN9739@mcvoy.com> 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