> If I don't do this, when I come back to the code an hour later I have no idea what its supposed to do or why I wrote it.
Many people write comments which are often nothing more than a really obvious transliteration of the code to English "foobar += 3; // Add 3 to the foobar".
These comments add little to nothing and often become worse than useless when they fall out of date and you end up with a cryptic "foobar += 7; // Add 3 to the foobar"
I find it helpful to imagine a codebase guru, someone who not only wrote the thing but has had years of experience maintaining and teaching to others... and the comment writes down what they would say if you asked them about it.
The guru wouldn't say 'adds three to foobar', they'd tell you about how the number used to be the obvious value of two but then the database choked when the boss was trying to store their golf scores in it, because foobar controls the whatzanits and there can be a race that requires it to have room for one extra. The guru would tell you _why_, and that's what a better comment will do.
Students of programming are often just writing what they're told to write. They don't necessarily have a strong grasp on the why, especially not a deep contextual grasp.
Many people write comments which are often nothing more than a really obvious transliteration of the code to English "foobar += 3; // Add 3 to the foobar".
These comments add little to nothing and often become worse than useless when they fall out of date and you end up with a cryptic "foobar += 7; // Add 3 to the foobar"
I find it helpful to imagine a codebase guru, someone who not only wrote the thing but has had years of experience maintaining and teaching to others... and the comment writes down what they would say if you asked them about it.
The guru wouldn't say 'adds three to foobar', they'd tell you about how the number used to be the obvious value of two but then the database choked when the boss was trying to store their golf scores in it, because foobar controls the whatzanits and there can be a race that requires it to have room for one extra. The guru would tell you _why_, and that's what a better comment will do.
Students of programming are often just writing what they're told to write. They don't necessarily have a strong grasp on the why, especially not a deep contextual grasp.