From mboxrd@z Thu Jan 1 00:00:00 1970 From: ggm@algebras.org (George Michaelson) Date: Wed, 21 Mar 2018 17:33:50 +0000 Subject: [TUHS] daemons are not to be exorcised In-Reply-To: References: <20180321141753.25C4418C088@mercury.lcs.mit.edu> <6c6699c0-15db-604a-181c-7dad282599e1@kilonet.net> Message-ID: I think there's a middle ground. saying "this is a loop" is not informative. saying "I did this as a loop because..." can be very informative. I think with short circuit evaluation and side-effects in C, this kind of code is especially worth commenting: people need to remember the right hand side of a complex set of expressions might actually not have done anything. Here at IETF a really cute corner-case of optimization-for-bug came up. Somebody who thought they had worked out a given packet in UDP dns messages always had a pair of specific chars 0x0c and 0xc0 in sequence (or something) and coded for it, not realizing they were coding below the outcome of a DNS label compression pattern which didn't always hold. Sometimes, people code from faulty or incomplete information. So this one, (for instance) would have been much better commented than not. It would have let the following people hit the coder with a thin whippy stick. On Wed, Mar 21, 2018 at 5:28 PM, Paul Winalski wrote: > On 3/21/18, Arthur Krewat wrote: >> >> It was instilled in me early on by my one and only mentor that someone >> that comes along later may have no idea what my code is doing. So >> comment. Even when it might be self-explanitory, comment anyway. > > In my 40-year career as a programmer, I've more than once had that > someone who comes along later be myself. > > I also apply what I call the Bus Principle. If you get hit by a bus > and killed, one of your colleagues is going to have to take over your > work. Give them a fighting chance with code comments, and maybe even > a design document for large or complex things. > >> I have noticed a lot of newer programmers these days that say >> (paraphrased): "Good code will explain itself" as a reason not to >> comment. Mostly C++ and Java programmers. >> >> I call bullshit on that. Not commenting is lazy. There's no reason NOT >> to comment. > > Amen to that! Good comments are one of the things that distinguishes > Software Engineering from mere programming. > > -Paul W.