/ home / Programming / Style /

Commenting

Commenting should be rare, and done in such a way that ensures removal upon code edits.

Why rare?
What are comment artifacts, and how can they mislead?
  1. // Draw seeds
  2. sneed.draw(seed);
  3. chuck.draw(feed);
  1. // Draw seeds
  2. chuck.draw(feed);
  1. sneed.draw(seed); is removed during testing.
  2. The comment // Draw seeds is left incase testing fails.
  3. The developer forgets about the comment and commits changes.
  4. The comment now sits above an unrelated line, misleading readers.
Won't the artefact be caught during a code review?
How can one freely comment while preventing artifacts?
  1. // Bad Comment
  2. this->sneed();
  3. this->seed ();
  4. // Bad Comment
  5. this->feed();
  6. /* Good Comment */
  7. {
  8. this->sneed();
  9. this->seed ();
  10. }
  11. this->feed(); // Acceptable Comment