It is easy to be ambiguous in comments. Comments, like code, can date easily, especially when developers use color coding to allow them to be “tuned out”.
In the following real example, the developer wrote comments describing a buffer size and length of time, not thinking ahead to when they might be changed. The next developer changed the code but forgot to change the comments.
byte[] buf = new byte[4096]; // buffer 2048 bytes long
:
return (1000L * 60 * 45); // very generous twenty minutes
The comment wordings could have been improved to make them more generic and resistant to change. At the same time, why not improve the return calculation clarity with a strategic MILLISECONDS_PER_MINUTE definition?
// buffer for creating dummy Invoice record
byte[] buf = new byte[4096];
:
// return msec delay before next attempt
return (MILLISECONDS_PER_MINUTE * 45);
Trap: Code comments should not be used for:
rants about other developers.
project documentation. Use the WIKI.
commenting the obvious.
swearing
Any of these may seem appropriate at the time but will reflect negatively on your professionalism.
