I've had the opportunity to do some code archaeology lately, and have found a few lessons that bear repeating when it comes to comments. There are a few patterns in use which need to be addressed:
Big Wall of Text
This long, rambling preamble can be found in many legacy applications. Though it does have some use in often providing a name to the faceless coder that is causing you such grief, other than that it has little reason to exist:
/************************************************************************
NAME: test
PURPOSE:
REVISIONS:
Ver Date Author Description
--------- ---------- --------------- ------------------------------------
1.0 7/8/2008 1. Created this package.
*************************************************************************/
This is a Comment
Really just a statement of the completely obvious in code. If these comments help the next developer of your code, you probably don't want them touching it anyway:
if (!Page.IsPostBack)
{
// first time
InitialSetUp();
}
Change Management:
Often put in as a CYA for developers who think the next person to view this code may question their decisions, so change documentation appears directly in the code:
//************************************************************************
//Input parameter changed to false for CommonFilter1.CheckBoxChecked,
//please see request-666899.
//************************************************************************
CommonFilter1.CheckBoxChecked(false);
Timestamp of Changes:
I really don't care when you did this, and if I did, source control could tell me:
//*********************************************************************************
// Changes made by OtherDeveloper on May-15,2002 at 6 pm.
//***********************************************************************************
Please feel free to share other examples of Commenting Anti-Patterns you have encountered!
posted @ Wednesday, August 13, 2008 11:47 PM