21 Mar
2018
21 Mar
'18
8:56 p.m.
On Wed, Mar 21, 2018 at 2:04 PM, Dan Cross <crossd(a)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
ᐧ