From mboxrd@z Thu Jan 1 00:00:00 1970 From: clemc@ccc.com (Clem Cole) Date: Wed, 21 Mar 2018 15:56:57 -0400 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: On Wed, Mar 21, 2018 at 2:04 PM, Dan Cross wrote: > > Critical to that, however, is the adjective "good", as in "good comments." > Writing comments can be incredibly useful, but writing *good* comments is a > learned skill that requires judgement and taste. > > ​....​ > > 1. A comment should never simply parrot the code: i++; // Increment i. > 2. A comment should sometimes explain *what* the code is doing. > 3. A comment should always explain *why* the code is doing what it's doing. > i.e. there is a difference between: ​ i++; // Increment i *v.s.* the line: ​ ptr->field++; // ensure reference count stays sane The former fails your first test, the second follows 2 & 3 as a note to my future self that this is where I am doing the this piece of support work (reference count maintenance). Clem ᐧ -------------- next part -------------- An HTML attachment was scrubbed... URL: