5 ms·

I'd rather someone over does it then under does it. The issue is that most things are obvious when you write the code, but that it's often not clear what's not

• danbruc 3y ago
  Obvious is and will be what the code does, not obvious is and will be why the code does it. I hate when people write comments explaining what the code does, I can just read the code and I will know. Why write it twice and open the possibility for inconsistencies? Is the comment wrong - forgotten to be updated maybe - as the code does something different then the comment says or does the code have a bug and it should actually do what the comment says? Also if your code can not be easily understood, then improve the code instead of trying to explain it in comments. Good reasons for comments explaining what the code does are few and far between. On the other hand I want people to comment why they do what they do and why they do it the way they do it, that are things that are hard or impossible to infer from the code. Unfortunately, at least in my experience, people tend to write way to many what and way to few why comments.