Commenting
Commenting should be rare, and done in such a way that ensures removal upon code edits.
Why rare?
- Good code is readable without comments.
- Poor code should be rewritten, not commented.
- Comments risk becoming artifacts after edits.
- Leftover comments will definitely mislead, and waste time.
What are comment artifacts, and how can they mislead?
- Take the code below as 'Before & After'
- // Draw seeds
- sneed.draw(seed);
- chuck.draw(feed);
- // Draw seeds
- chuck.draw(feed);
sneed.draw(seed); is removed during testing.- The comment
// Draw seeds is left incase testing fails.
- The developer forgets about the comment and commits changes.
- The comment now sits above an unrelated line, misleading readers.
Won't the artefact be caught during a code review?
-
- Unlikely.
- All developers are weary to delete comments.
- Will sooner assume that they are misreading the code, than to doubt the comment.
How can one freely comment while preventing artifacts?
- Never dedicate a single line to a comment,
- Unless that comment is followed by a code block:
- // Bad Comment
- this->sneed();
- this->seed ();
- // Bad Comment
- this->feed();
- /* Good Comment */
- {
- this->sneed();
- this->seed ();
- }
- this->feed(); // Acceptable Comment
/* Good Comment */ is clearly applicable to the block.- When folded, editors will compound the block to the comment.
- Delete the comment, and one deletes the block.
- If the block contents are removed, but the block remains, the reader can assume the comment is an artifact.
// Acceptable Comment will likely be removed with the line.- The risk of artifacting is minimal.
- If the line however is edited, the comment can become misleading and should be avoided if possible.