4 ms·
> I put comments so future me will remember what the heck I was thinking when I wrote it. People who don't do this: please don't underestimate the importance o
by zepolen 16y ago
> I put comments so future me will remember what the heck I was thinking when I wrote it.
People who don't do this: please don't underestimate the importance of this.
Be descriptive as possible with the comments on possibly clever/incomplete code - you will thank yourself months later when you realise:
x += 1 # border
makes no sense to you.
Yes, at the time you wrote the code, it's perfectly obvious to you, but you will forget it and think to yourself next time: 'wtf is this being incremented by 1 for, what about the border, is the border being incremented?'
If you hesitate even for a second about the possibility of your code being misinterpreted in the future, either fix it on the spot or add a damn descriptive comment.
- silentbicycle 16y agoYou can drown code in comments, though. In your example, saying "x += borderW" would be as expressive, and tie that context to everywhere else it was relevant. Some comment issues are really better handled as (variable/function/method/structural) naming issues. Comments are better for explaining the rationale behind seemingly arbitrary or crazy design decisions - "I would have done obvious thing X, but that causes huge problem Y". Why, rather than what. For things that provide important context, but could not be expressed in the language itself. Many "what" comments should instead be static typing declarations, asserts, or tests. At least that way, people will notice when they no longer hold. Comments are just declarations the language ignores. (Citations, like "implements algorithm X, see Okasaki 1999", are fine though.)
- zepolen 16y agoThe border example was a bad one, I meant what you said.