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.

view plain print about
1<cfsetting enablecfoutputonly="true">
2
3<!---
4 ===========================================================================
5// CLASS/COMPONENT:
6
7// wwwroot.Admin.myComponent
8
9//
10// DESCRIPTION:
11
12// Here is a brief description of 'myComponent'
13
14//
15// AUTHOR:
16
17// Steve 'Cutter' Blades (SGB), web.adminATcutterscrossingDOTcom
18//
19// COPYRIGHT:
20
21// Copyright (c) 2007 CuttersCrossing, Inc. All Rights Reserved.
22
23//
24// REVISION HISTORY:
25
26//
27// *****************************************************************************
28
29// User: SGB Date: 01.14.07
30
31// Initial Creation
32
33//
34******************************************************************************
35===========================================================================
36--->

37
38<!--- The rest of the code is included here --->
39
40<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:

view plain print about
1<!---
2//    SGB [11/27/2006]:    Added a param in the event that the value is not included within the querystring
3 --->

4<cfparam name="url.event" default="" />

JavaScript example:

view plain print about
1/*
2//    Function to validate a form
3// Input: fields array of fields to be validated
4
5// Output: boolean value for success or failure
6
7*/

8function validateForm(fldsObj){
9    success = 1;
10    // Validation processing would reset 'success' on failure
11
12    return success;
13}

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