Commenting Code for Your Future Self

Pen on a white notebook

Comments that restate the syntax waste space. Comments that explain why a weird choice was made save hours months later.

Write the intent in one sentence above non-obvious blocks: why a timeout is 3 seconds, why you skip a null check, why a loop runs backward. Prefer linking to a ticket or design note over a novel in the source file.

When you paste a snippet into a new project, update the comment with the new context. Stale comments are worse than no comments because they create false confidence.

If a function needs a paragraph of explanation, that is a signal to rename it or split it. Clear names reduce the comment burden.