It is very easy to create your own automated code review, most reviews are just 4 lines of CFML code!

How The Code Review Tool Works

The code review tool first reads all the configuration settings, and review definitions. Next a list of files is generated recursively from the base path that the user wishes to review. All of the files are sequentially read, and parsed. The review definitions contain a variable called tagListener which is a list of tag names that the particular rule is interested in. Each file is checked for each tag listener in every review. When a file has an instance of the tag that the review is listening for, the review code is executed. If a file has multiple instances of the tag the review code will be executed multiple times.

The review code has several variables available which can be used to determine if there are any issues associated with a particular tag instance. If there are issues in the tag instance, then the issue is reported with the AddIssue function.

Here is some pseudo code that illustrates the process:

for each file
  for each review definition
    for each tag listener
      if file has tag
        execute review
      end
    end
  end
end

Step 1 - Create the Review Definition

Open the file codereview/config/custom.reviews.cfm. Create a structure in this file using the example below.

Example Review Definition Structure:

<cfset config.reviews.myreview = StructNew()>
<cfset config.reviews.myreview.name = "IMG tags should define height and width">
<cfset config.reviews.myreview.description = "Set the height and width attribute on your img tags.">
<cfset config.reviews.myreview.type = "style">
<cfset config.reviews.myreview.severity = 3>
<cfset config.reviews.myreview.taglistener = "img">

• Review File Name - this should be a file name with no special characters, and all lower case (eg: myreview). The name of structure (eg: config.reviews.myreview) corresponds to your review code file name.
• Name - the friendly name for your review (eg: "IMG tags should define height and width")
• Description - a description of your review (eg: "You should specify height and width in the IMG tag."). This may be thought of as the error message that shows up on the report.
• Type - the issue type (eg: "style"). We define several issues such as performance,style,security,accessibility,etc. You can define new types but you need to add them to the configuration under "Review Types". These can be used to filter code review results.
• Severity - the severity indicator should be a number between 1 and 5, 5 being the most severe (eg: 3). This is only used to filter your reviews, for instance a user may choose to ignore all rules with a severity below 2.
• Tag Listener - a comma separated list of tag names, when a tag in the list is encountered (eg: "img") in a file your review code will be executed.

Step 2 - Write your review code

Reviews are stored in the directory codereview/framework/reviews/. Create a file using the file name specified in Step 1 (remember all lower case, no special characters). The file you just created will be executed every time an instance of a tag in your taglistener list is found. Each time it is executed several variables are set, here's some variables you can use:

Review Variables

• tagName - the name of the tag at the current position
• fileContents - a string containing the contents of the current file
• filePath - the full path to the current file
• fileName - the name of the current file (eg: file.cfm)
• fileExt - the extension of the current file (eg: .cfm)
• tagInfo - a structure containing information about the current tag.
• tagInfo.attributeContent - a string containing the inside of the start tag (excluding the tag name) (eg: src="/codereview/docs/1/img.gif" /)
• tagInfo.innerContent - the content inbetween the start tag, and end tag. If there is no end tag, this will be an empty string.
• tagInfo.startPos - the position of the start tag in the file
• tagInfo.startTagEndPos - the position of the end of the start tag
• tagInfo.endTagPos - the position of the end tag in the file, if there is no end tag then this is the same as tagInfo.startTagEndPos

Using the above variables you can easily determine if the tag instance has the issue your looking for. If you find the issue your looking for, you can call the AddIssue function. The function expects three arguments: an issuename (this should be your file name), a context (string showing where the problem is, code sample), and the position in the file where the issue begins. Here's an example code review that makes sure a tag has the height attribute defined:

<cfif NOT ReFindNoCase("height[[:space:]]*=", tagInfo.attributeContent)>
	<cfset context = "<" & tagName & tagInfo.attributeContent & ">">
	<cfset AddIssue("myreview", context, tagInfo.startPos)>
</cfif>

Yes that's all it takes to write a review 4 lines of code is very typical! Getting handy with regular expressions will also save you a lot of code. Checkout this regular expression howto, or this book for more info on Regex in ColdFusion.

Step 3 - Enabling the review

Now all thats left to do is enable your review, so the framework knows about it. This is done by adding the file name of your review to the Reviews list in the configuration web page in the tool (visit index.cfm in your web browser and click on configuration).