Quote:
Originally Posted by cjl2625
I add comments when it isn't totally clear what a piece of code is doing.
For that tank drive example, I wouldn't have any comments (aside from the negating one side thing, perhaps), since that code is pretty self-explanatory. Comments there seem redundant.
When there's too many comments, I find it bothersome and intrusive.
For single lines whose functions are unclear or confusing, it's worth a comment, but sometimes I neglect to do that (which is a bad habit of laziness).
And perhaps before each method or section of code, I'll sometimes add a line of explanation.
I suppose I'm guilty of sometimes being too cryptic in variable names and documenting my code poorly. Since I basically wrote all the team's code for the past 4 years, I've been able to get away with it, but it's a habit I should break.
|
You are not the target of your comments, the person behind you is the target.
What may be clear to you may be "clear as mud" to the one following you.
I suggest commenting every
section, not
line. And I suggest having someone whom is learning the language to try and interpret your code ... if they cannot then you need more comments.