On Wed, Mar 21, 2018 at 2:04 PM, Dan Cross <crossd at gmail.com> 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: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/6803fa6c/attachment.html>