Commenting code so future you understands it
A comment is a note to the reader. The compiler ignores it, which is exactly why it must be written for a person.
Two forms
C#
// a single line note
/* a longer note
that spans lines */What a good comment says
- Why the code does something surprising.
- What a magic number means.
- Which business rule the code is protecting.
What a bad comment says
A comment that restates the code adds nothing. Incrementing a counter does not need a note that says increment the counter. Save the space for the reasoning.
Use the editor shortcut. Select several lines and use the comment toggle rather than typing markers by hand, so the block stays aligned and easy to undo.
Commented code is easier to debug, because you can follow your own reasoning as you step through it.