When you land your first job as a ColdFusion developer, you will most likely be added to a team of developers already in process on a project, or you may be taking the place of someone who is no longer there. With either situation, being able to quickly acclimate yourself to the application you will be developing is important. How do we do that?
It is good programming practice to always leave comments in your ColdFusion code so that others who may need to maintain that code when you aren’t around can easily understand what is going on under the hood. If you’re lucky, the application you will be working on had a good programmer who has done just that. If however, you aren’t that lucky, we can use some basic commenting procedures to go back through and learn the application and document it as you go. These tips will also help you when documenting your own code as well so that nobody ever has to come in behind you and comment your code for you.
There are several methods I use every day to make my code easy to read and understand.
You can add your own descriptive comments to your code at any place by simply surrounding the comment with special formatting tags that hide the comment from view. ColdFusion server side commenting will never be visible to the browser, while HTML commenting is client side and always available. See below for examples.
Server Side Commenting <!--- I am a ColdFusion comment and am processed on the server, so the browser can never see me---> <cfscript> //Single line comment inside a cfscript tag, not visible to the browser /* MULTI LINE COMMENT */ </cfscript> Client Side Comment <!-- I am an HTML comment and am visible to browsers via the view source option -->
Descriptive comments using the above coding practices are limitless in size. You can be descriptive as you like, but typically most can be commented in a fairly short and straight forward manner. For example, many times when I am creating a new page within an application I will create a standard comment header to describe what the page I am writing is intended to do.
<!--- Creator: Misty Spears Date created: 9/9/2013 Last Updated: 9/11/2013 Purpose: This is the action page that the account update form is submitted to. All functions for add, editing and deleting an account is done here. --->
Within the same page, I have to run a query to check for an active status on an account. To make my code understandable, I am going to leave an inline comment above to let the reader know what I’m doing. You’ll also notice I named the query a very understandable name to make it fairly obvious what the query does.
<!--- Check if this account is active ---> <cfquery name="CheckforActiveStatus"> Select id, isactive from Accounts where username = '#username#' </cfquery>
Variable Naming Practices
You most likely use variables in your code on a daily basis. If you remember, from Basic Concepts: Variables and Data Types, a variable is a method to store data to use later on in your code. Because it is such a common coding practice, you should name your variables in a way that “self comments” and is obvious what the data holds.
For example, take a look at the following code.
<cfset var1 = “January”>
Does the variable name “var1” tell you anything about what the value January is? It certainly doesn’t. There is nothing about that line of code that could tell someone reading your code what the variable is holding, other than actual value. However, by simply renaming it to something a little more useful, you are making it clear what the variable is and no additional comments would even be necessary.
<cfset mybirthmonth = “January”>
Page Naming Conventions
Along the same lines as the variable naming conventions, your page names should also be descriptive as to what they do. This will make it easier for other codes to work in the same folder with 100 pages in it and find the one they are looking for easily. For example, the name “account_update.cfm” is pretty obvious that the function of that page is to update an account.
By following these simple practices now, your fellow coders will appreciate being able to understand your code and enjoy working with you. You may even appreciate it yourself when you come back to edit that page in 6 months and can easily pick that code back up and be able to follow your own comments.