Code Comments For The (Team) Playa

Posted: May 15th, 2009 | Author: | Filed under: ColdFusion | No Comments »

Word up, dawgs? Consider the following code…

Example 1 – Some Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

<cfscript>
	if(NOT IsDefined("url.Page")){
		Application.Util.abort();
	}
	variables.action = "";
	variables.Cheese = "";
	variables.cheeseId = 0;
	variables.datasource = Application.datasource;
	variables.errorMessage = "";
	variables.message = "";
	variables.Page = url.page;
	variables.queryCheeses = "";
	variables.validationArray = "";
	variables.viewState = "";
	if(IsDefined("url.action")){
		variables.action = url.action;
	}
	if(IsDefined("url.cheese") AND IsNumeric(url.cheese)){
		variables.cheese = url.cheese;
	}
	if(variables.userIsAuthenticated == false){
		Application.Util.abort();
	}
	switch(variables.action){
		case "cheeseAdd":{
			variables.Cheese = CreateObject
				(
				"component",
				"Cheese"
				).init
					(
					datasource = variables.datasource
					);
			variables.validationArray = variables.Cheese.validateForm
				(
				formStructure = form,
				validationArray = variables.validationArray
				)
			if(ArrayLen(variables.validationArray) EQ 0){
				variables.Cheese.setProperties(formStructure = form);
				variables.Cheese.create();
				StructClear(form);
				variables.message = "Cheese Added.";
			}else{
				variables.viewState = "cheeseEdit";
			}
			break;
		}
	variables.queryCheeses =
		CreateObject
			(
			"component",
			"Cheeses"
			).getCheeses
				(
				datasource = variables.datasource,
				isActive = true
				);
	Application.Util.param(name="form.cheeseName" default="");
	Application.Util.param(name="form.cheeseDescription" default="");
	if(ArrayLen(variables.validationArray) GT 0){
		variables.errorMessage = Application.Util.renderErrorMessage
			(
			validationArray = variables.validationArray
			);
	}
</cfscript>
<cfoutput>
	<h2>Cheeses</h2>
	<cfif Trim(variables.errorMessage) NEQ "">
		#variables.errorMessage#
	<cfelseif Trim(variables.message) NEQ "">
		#variables.message#
	</cfif>
</cfoutput>

What’s missing here? CODE COMMENTS. If you aren’t commenting your code you fall into two categories:

1. People Who Don’t Know How To Add Code Comments (really?)
2. People Who Don’t Care and/or Are Lazy

Now for the “People Who Don’t Know How To Add Code Comments” crowd here’s the syntax for code comments…

Example 2 – Code Comments in HTML

1

<!-- I am an HTML code comment -->

Example 3 – Code Comments in ColdFusion

1
2
3
4
5
6
7
8
9
10
11

<!--- I am a single-line ColdFusion code comment --->
<!---
I am a multi-line ColdFusion code comment
--->
<cfscript>
	// I am a single-line ColdFusion code comment in a CFSCRIPT block
 
	/*
	I am a multi-line ColdFusion code comment in a CFSCRIPT block
	*/
</cfscript>

As you can see adding code comments is not difficult.

A message to those who fall under the “People Who Don’t Care and/or Are Lazy” category: you are putting your clients, your systems and your career into a state of unnessecary risk. Stop doing that!

In the small and medium-sized systems that I’ve been developing recently I’ve developed a standardized way of coding. This standard is constantly changing, as I base it on lessons learned from previous work, the requirements for each system and my skill level at the time. One “standard” that I make an effort to adhere to is “Before writing any code use code comments to sketch out the the general structure of an application”.

On a recent small-sized system I combined the Controller and View into a single include. Here is a sample approach…

Example 4 – Page Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<cfscript>
 
	// CONTROLLER
 
	// required input arguments
 
	// variable declarations
 
	// optional input arguments
 
	// security
 
	// switch action
 
	// Objects
 
	// get query results
 
	// cfparams
 
	// render form validation HTML
 
</cfscript>
 
<!--- VIEW --->

Once I had the above include structure completed I quickly captured it into a CFEclipse snippet (a subject for another post).

Lets take a look at the comments from Example 4 combined with the code from Example 1…

Example 5 – Code With Comments

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

<cfscript>
 
	// CONTROLLER
 
	// required input arguments
	if(NOT IsDefined("url.Page")){
		Application.Util.abort();
	}
 
	// variable declarations
	variables.action = "";
	variables.Cheese = "";
	variables.cheeseId = 0;
	variables.datasource = Application.datasource;
	variables.errorMessage = "";
	variables.message = "";
	variables.Page = url.page;
	variables.queryCheeses = "";
	variables.validationArray = "";
	variables.viewState = "";
 
	// optional input arguments
	if(IsDefined("url.action")){
		variables.action = url.action;
	}
	if(IsDefined("url.cheese") AND IsNumeric(url.cheese)){
		variables.cheese = url.cheese;
	}
 
	// security
	if(variables.userIsAuthenticated == false){
		Application.Util.abort();
	}
 
	// switch action
	switch(variables.action){
 
		// case cheeseAdd
		case "cheeseAdd":{
 
			// create a Cheese object
			variables.Cheese = CreateObject
				(
				"component",
				"Cheese"
				).init
					(
					datasource = variables.datasource
					);
 
			// validate the form
			variables.validationArray = variables.Cheese.validateForm
				(
				formStructure = form,
				validationArray = variables.validationArray
				)
 
			// if the form is valid, add the cheese to the database
			if(ArrayLen(variables.validationArray) EQ 0){
				variables.Cheese.setProperties(formStructure = form);
				variables.Cheese.create();
 
				// clear out the form structure
				StructClear(form);
 
				// celebrate your success
				variables.message = "Cheese Added.";
 
			// else the form is not valid
			}else{
				variables.viewState = "cheeseEdit";
			}
 
			break;
		}
 
	// Objects (none for this page)
 
	// get query results
	variables.queryCheeses =
		CreateObject
			(
			"component",
			"Cheeses"
			).getCheeses
				(
				datasource = variables.datasource,
				isActive = true
				);
 
	// cfparams
	Application.Util.param(name="form.cheeseName" default="");
	Application.Util.param(name="form.cheeseDescription" default="");
 
	// render form validation HTML
	if(ArrayLen(variables.validationArray) GT 0){
		variables.errorMessage = Application.Util.renderErrorMessage
			(
			validationArray = variables.validationArray
			);
	}
 
</cfscript>
 
<!--- VIEW --->
 
<cfoutput>
 
	<h2>Cheeses</h2>
 
	<cfif Trim(variables.errorMessage) NEQ "">
		#variables.errorMessage#
	<cfelseif Trim(variables.message) NEQ "">
		#variables.message#
	</cfif>
 
	<!--- the rest of the page goes here...	--->
 
</cfoutput>

Much better, eh? It’s worth noting that I added a few additional comments and extra line breaks.

Adding code comments is easy to do, it helps to organize your thoughts and it helps other developers that will work with your code.

Leave a Reply