Consistently poor comments are worse than none at all because the developer soon gives up reading them.
Do not add comments to code that is obvious. This obscures code and makes it more difficult to comprehend, opposite to the intended effect.
index-=1; // subtract 6 from index
:
for (i=0;i<index;i++) // loop
This would be far better written as below.
index-=1; // skip the trailing EOF byte that's always present
:
// go through all bytes to build a total.
for (i=0; i<index; i++)
Do not comment links from the code back into chapter or page numbers of documents as they will quickly get out of date when the document is unwittingly updated.
// see page 273, chapter 8.3.31 of functional requirements document
int maxUsers = 256;
If there needs to be a reference, use terms that will not change, such as task tracking system numbers or general chapter names.
// See functional requirement doc, User Access section
// Jira: SHOP-328
int maxUsers = 256;
Don't use "comment templates" unless you have a strict review process, as these tend to be completely ignored or cut and pasted with old information present.
/**
* Title: PENDING
* Description: PENDING
* Copyright: PENDING
* Company: PENDING
* @author PENDING
* @version PENDING
*/
Don't comment out obsolete code that ought to be removed completely, just remove it since the source code control system will keep the original copy.
// obsolete - remove some day
// total.add(value);
If you are not sure that code can safely be removed, no changes should be made to the code until you are sure. Ask advice.
