Commenting Individual Lines
- Avoid self-indulgent comments
memcpy( ptrDest, ptrSrc, nBytes ); // The Pink Panther Movie Rocks !!!
- Avoid endline comments on single lines
memcpy( ptrDest, ptrSrc, nBytes ); // Save a copy of 1-ring
vs.
// Save a copy of 1-ring
memcpy( ptrDest, ptrSrc, nBytes );
- Avoid endline comments meant to apply to multiple lines of comments
for (currIdx = 0; currIdx <= nElems; currIdx++) // Compute min/max
{
...
}
vs.
// Compute min/max
for (currIdx = 0; currIdx <= nElems; currIdx++)
{
...
}
- Use endline comments to annotate data declarations
int upperSentinel = nElems; // sentinel used to prevent sorting from running past upper end of array
int lowerSentinel = 0; // sentinel used to prevent sorting from running past lower end of array
- Use endline comments to annotate routine parameters
bool BuildOneRing
(
const TINvertex * origVertex; // IN - original vertex
TINvertex * newVertex; // OUT - new vertex with valid 1-ring
)
{
...
}
- Avoid using endline comments for maintenance notes
for (i = 0; i < maxElments-1; i++) // Fixed bug #4251 on 06/15/08 (SDB)
--
ShawnDB - 16 Jun 2008
to top