Comments
At work I (with heavy input from the rest of the team) am writing these guidelines for our development practices, so that everyone is working 'on the same page.' I will share this series here for others who may want to know how some folks do it.
First and foremost is documentation. We have an extremely large system, currently made up of nearly 7,000 ColdFusion, XML, Javascript, Cascading Style Sheet, ActionScript, and Flash templates. The original authors of these templates were spread fairly thin, working a variety of tasks while attempting to produce a usable product base to build our company upon. Because of this a large majority of our system is completely un-documented. Now, as a matter of standard practice, every template touched by a developer is given, at minimum, a document header comment to create some form of initial documentation.
<!---
===========================================================================
// CLASS/COMPONENT:
// wwwroot.Admin.myComponent
//
// DESCRIPTION:
// Here is a brief description of 'myComponent'
//
// AUTHOR:
// Steve 'Cutter' Blades (SGB), web.adminATcutterscrossingDOTcom //
// COPYRIGHT:
// Copyright (c) 2007 CuttersCrossing, Inc. All Rights Reserved.
//
// REVISION HISTORY:
//
// *****************************************************************************
// User: SGB Date: 01.14.07
// Initial Creation
// ******************************************************************************
===========================================================================
--->
<!--- The rest of the code is included here --->
<cfsetting enablecfoutputonly="false">
This is a very basic header comment. Opening and closing comment identifiers will be different for Javascript, ActionScript, Flash files, or Style Sheet documents, but the basic structure would be the same. First you have the path to the document being worked on. This is a dot notated reference to the path, in this case a ColdFusion Component (myComponent.cfc) locatated in /wwwroot/Admin/. Documents other than component classes would also include their document extension (i.e.: wwwroot.Admin.myTemplate.cfm). A brief description of what the template does is included next, followed by the name and email of the author of the template (only to be used on new documents), and the copyright notice. The final area is the revision history. This is the most important area within this documentation, as every change made to a template will be documented here, with the most current revision being the top item then going downward for each revision made to a template. Each revision will be listed with as much detail as possible, stating the initials of the developer making a change and the date that it was modified. Similar revision notes should also be made inline within the document at the location of any revisions, with the same data included (initials and date stamp). You should also note the cfsetting tags. These are utilized to minimize white space output in the generated page, and are only used within .cfm templates, but require the developer to pay close attention to the code contained between them, as display code will only be rendered if it exists within cfoutputtags (or within the writeoutput() statement of a cfscript block.
Inline revisions:
// SGB [11/27/2006]: Added a param in the event that the value is not included within the querystring
--->
<cfparam name="url.event" default="" />
JavaScript example:
// Function to validate a form
// Input: fields array of fields to be validated
// Output: boolean value for success or failure
*/
function validateForm(fldsObj){
success = 1;
// Validation processing would reset 'success' on failure
return success;
}
Comments are handled differently with different languages:
- ColdFusion (CFML) - <!--- Comment --->
- HTML/XHTML - <!-- Comment -->
- Cascading Style Sheet - /* Comment */
- ColdFusion (CFScript), JavaScript, Flash/ActionScript -
- Multiline - /* Comment */
- Single Line - // Comment
Also, what happens when the person whose contact information is in the file no longer works with you, or is that not a concern?
Were you finding that the original programmers were using hard-to-discern meaning in their choice of variable and file names?
Our system at work is a shared template application setup, consisting of something near to 7,000 CF templates, CF components, JavaScript files, Flash files, and XML documents, developed over the last 5-6 years by just under a dozen different programmers. Prior to my immediate boss being hired there was almost never any documentation within the code, variable scoping is abismal, etc. Anything my boss generated was built with some more forthought, and once I was hired every template touched received documentation (at the least). Now that we have hired two new developers (one senior, one entry) we realized we really needed to standardize.....And yes, we had variables of totally unknown scope named 'i', and files like 'FormProcessor.cfm'. "let's guess where this one belongs..."
sporter:
Yes, it is for white space suppression. If you take a closer look at the example you will see a 'Your code goes here' comment prior to the enablecfoutputonly="false" line. The reason we open and close it (or close it and open it, depending on your point of view) is because you never know when the file you are working on may be a cfincluded template. The including template might not have processing directives (yet) and we don't want to 'hide' any content inadvertantly.
Dan:
Fantastic idea for delineating 'temp' and 'perm' comments. Might have to adopt that.
matter what you do.