ColdFusion Coding Guidelines

8,759
-1

Published on

This document is (one of many) coding style documents available for ColdFusion on the web. This one combines the best practices of several noted ColdFusion developers into a single cohesive coding style guideline document you can implement immediately with excellent results.

0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
8,759
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
147
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

ColdFusion Coding Guidelines

  1. 1.    ColdFusion Coding Guidelines  Release 1.1                              3 February 2010     
  2. 2. Naming, Comments & Layout This section provides guidelines on naming conventions (for files, tags, variables etc), comments and source code layout. Naming This section provides guidelines for naming various entities in your ColdFusion code.  General Naming Guidelines All entities should be named for readability ‐ names should be readable English words or phrases. The primary function or purpose of any entity should be obvious from its name. In general, "verb‐noun" and "adjective‐noun" phrases are the most natural choice, e.g.,: course_list_output.cfm ‐ invoked in a URL calculate_sales_tax.cfm ‐ a custom tag productInformation.cfc ‐ a ColdFusion component userName, lastName, getBankBalance ‐ a variable, function, attribute, property etc qGetQuery, qPutQuery, qDelQuery – a <cfquery> variable name should always begin with a lowercase ‘q’ to quickly identify the variable as a query. The singular noun is preferred. In general, .cfm files will be lower case with words separated by underscores when used on Search Engine (SE) facing pages (e.g. product_list.cfm). Coldfusion pages not SE facing (e.g. user management pages, members only pages, etc.) can be either lowercase words separated by underscores or headlessCamelCase (e.g. memberList.cfm). All .cfc files will be headlessCamelCase (e.g. myColdfusionComponent.cfc). Abbreviations Abbreviations and acronyms should be avoided and full nouns and verbs utilized instead. Only a few, widely understood, acronyms or abbreviations may be used such as ID, UUID, PKEY, etc. Such abbreviations and acronyms will be headlessCamelCase, unless they are part of a filename that forms part of a SE facing URL, in which case they will be lowercase, e.g., userId ‐ variable, attribute, property, etc. memberUuid – variable, attribute, property, etc. pkeyUser – variable, attribute, property, etc. set_user_id.cfm ‐ invoked in a SE (Search Engine) facing URL deleteMemberUuid.cfm – invoked in a non SE facing URL delete_pkey.cfm – invoked in a SE facing URL    
  3. 3. File Naming Suffixes:   HTML files end in .html   CFML files end in .cfm   Component files end in .cfc   XML files end in .xml    CSS files end in .css   JS files end in .js In general, follow our existing file naming conventions for files: all SE facing URL‐accessible filenames shall be lowercase, with words separated by underscores (e.g. get_product_list.cfm). All non SE facing URL‐accessible filenames shall be headlessCamelCase (e.g. addNewProduct.cfm). Filenames must never contain spaces!  Note: Application.cfc, Application.cfm and OnRequestEnd.cfm are the only exceptions to the lowercase filename rule for URL‐accessible files and must have exactly the case shown!  ColdFusion Components The component name shall be headlessCamelCase; all method names, property names and instance names (variables referring to components) shall be headlessCamelCase. All references to component names in code shall match exactly the case of the implementation filename, i.e., references will be path.to.headlessCamelCase.  Custom Tags Custom tags should not be used, however in the event that you must write one, the names will be lowercase_words. Their implementation filename should be lowercase_words.cfm, stored somewhere within the {cfmxroot}/extensions/customtags/ hierarchy (so custom tags cannot be invoked directly via a URL). They should be invoked using a tag prefix (defined using cfimport before the first use of any custom tags in each file ‐ cfimport tags should be grouped together near the top of the file) e.g., <pfx:lowercase_words ...> ... </pfx:lowercase_words>. The pfx will usually be the lowest‐level directory containing the tags, e.g., mmlf for {cfmxroot}/extensions/customtags/mmlf/ ‐ used like: <cfimport taglib="/customtags/mmlf" prefix="mmlf" /> ... <mmlf:ssi virtual="/path/to/file.html" /> The expectation is that directories under the Custom Tag Paths will have unique names ‐ the tag prefix must be unique within a page.  
  4. 4. Note: CFX tags will not be used ‐ instead write Java tag libraries and <cfimport ...> them (assuming you cant write the tag in CFML for some reason). Type Names The names used to reference ColdFusion types (e.g., in type= and returntype= attributes) shall be lowercase for built‐in types (e.g., boolean, string). The names used to reference user‐defined types (i.e., ColdFusion Components) shall exactly match the case of the implementing filename, e.g., newsArticle, newsItem, MachII.framework.Listener. Built‐in CFML Tags, Attributes & Operators Built‐in CFML tags shall be lowercase, just like our HTML tags. Attributes for CFML tags shall be lowercase (mirroring XHTML‐compliance). Built‐in operators shall be CamelCase (e.g. IsDefined, Encrypt, Decrypt, DateFormat). Note: Simple built‐in operators will be all uppercase, e.g., IS, AND, OR, NOT. Attributes, Fields, Functions, Methods, Parameters, Properties & Variables All these entity names will be headlessCamelCase. To enhance readability, boolean attributes and variables should generally begin with "is" or "has", e.g., <cfif hasFlash> ... </cfif>. Function and method names should generally be of the form verb() or verbNoun(), e.g., read(), getName(). Attribute Values All attribute values to all tags ‐ except cfset, cfif and cfreturn ‐ will be quoted, usually with double quotes ("). Single quotes () may be used if the attribute value already contains a double quote. In cfset, the attribute name is always a variable name (possibly evaluated, e.g., arr[i]) and the apparent attribute value is really an expression. In cfif and cfreturn, the attribute is really an expression. String values in expressions will be quoted (with " or  as appropriate). Numeric values in expressions will not be quoted. Variable names in expressions will not be quoted, so that pound signs (#) are not needed, i.e., variableName instead of "#variableName#". The attribute name in cfset ‐ the variable name ‐ will not be quoted. You may use evaluated variable names like "caller.#resultVariable#" or "varname_#index#" – OR use caller[resultVariable] or variables["varname_" & index] instead. The only acceptable boolean attribute values are True and False ‐ which should always be unquoted. You may substitute 1 and 0 for True and False calculations where the results are to be directly inserted into a database. 
  5. 5.  Examples: <!‐‐‐ string requires quotes: ‐‐‐> <cfset x = "A string" />  <!‐‐‐ other expressions require no quotes: ‐‐‐> <cfset y = len(x) /> <cfif z gt y * 2 >  <!‐‐‐ simple variable requires no quotes: ‐‐‐> <cfset request.value = z />  <!‐‐‐ evaluated variable requires no quotes: ‐‐‐> <cfset caller[result] = z /> Scope Names Scope name qualifiers should be used with all variables (except var scope variables inside functions), where there is any possibility of a collision with a name in another scope. Since ColdFusion looks up the scope chain if it cannot find a name in the current scope, variables scope should be used for safety, to avoid accidentally picking up the wrong variable in an outer scope, e.g., a cookie.  Inside components, variables scope refers to non‐public instance data (and this scope refers to public instance data). If you want a local variable in a function, you should use var and then set the variable to declare it (at the top of the function). Within cffunction, you can use either of the following styles: <!‐‐‐ using tag syntax for the function body: ‐‐‐> <cffunction name="bar">     <cfset var localVar = 0 />     <cfset var anotherLocalVar = 0 />     ... </cffunction>  <!‐‐‐ using script syntax for the function body: ‐‐‐> <cffunction name="bar">     <cfscript>         var localVar = 0;         var anotherLocalVar = 0;         ...     </cfscript> </cffunction> Inside components, there are two special scopes: this and variables. When variables are qualified with this scope, they become public data members of the component instance and accessible to 
  6. 6. code outside the component. When variables are qualified with variables scope, or left unqualified ‐ using the unnamed scope, they become non‐public data members of the component instance (and, therefore, are not accessible outside the component). This is important since unqualified variables within functions will persist for the lifetime of the instance ‐ which may not be what you intended ‐ hence the need to use var to declare local variables!  Example: <cfcomponent>     <cffunction name="example">         <cfset var localVar = "Just in this function" />         <cfset VARIABLES.nonPublicVar = "Non‐public data member" />         <cfset anotherNonPublicVar = "Not recommended ‐ use variables" />         <cfset THIS.publicVar = "Public data member" />     </cffunction>     <cffunction name="more">         <cfset var localVar = "Different to example localVar" />         <cfset var x = VARIABLES.nonPublicVar & " set in example above" />     </cffunction> </cfcomponent> Note: THIS.member and member denote two distinct variables in distinct scopes (but dont do this: in general, name collisions are bad practice and cause debugging headaches!). VARIABLES.member and member denote the same variable (assuming member is not also declared with var) ‐ always use VARIABLES.member for clarity. Scope names should always be capitalized: Examples: FORM.myFormField URL.myURLVar  VARIABLES.pageVar ARGUMENTS.argName THIS.publicVar Query Naming Query names follow the same convention as other variable names, using the verbs Update (Upd), Insert (Put), Delete (Del), or Select (Get) as follows:  Query Type  Pattern  Example Select Data  qGetQueryname qGetCustomer Update Data  qUpdQueryname qUpdCustomer 
  7. 7. Insert Data   qPutQueryname qPutCustomer Delete Data   qDelQueryname qDelCustomer Comments This section provides guidelines on commenting your source code. In general, we should comment code to assist other developers work on it in the future. We do not want our comments to be visible to the public so we do not want to generate HTML comments from CFML ‐ we use <!‐‐‐ ... ‐‐‐> in CFML which does not get published into the HTML. This means that for file types that can be accessed directly over the web, such as JavaScript include files, XML files and CSS style sheets, we should keep comments to a minimum ‐ documentation for such files must be maintained separately, in the "projects" area of our internal site for example. Comments are there to be read ‐ consider your audience! General Guidelines Write CFML style <!‐‐‐ ... ‐‐‐> comments, for all important entities, that describe what code does and why ‐ document the how if it is not obvious. When you make a change, comment it. Identify the change with the date and your user name: <!‐‐‐ 2001‐11‐26 springled Expanded the Comments section ‐‐‐> When you want to leave a note about a bug to be fixed or functionality to be added, put TODO: in front of the actual comment so developers can easily search for them: <!‐‐‐ 2001‐11‐26 springled TODO: Incorporate everyones feedback ‐‐‐> Additional standard search keywords can be added after TODO: e.g., FIXME:, NOTE: ‐ this is very important as it helps your audience, other developers. Furthermore, standard tags like this can be read by code editors such as Eclipse to create a "task list" whenever youre working on a file. <!‐‐‐ 2001‐11‐26 springled TODO: BUG: Fails on Fridays ‐‐‐>  File Comments Each CFML file should begin with an CFML style <!‐‐‐ ... ‐‐‐> comment containing the filename and a standard copyright message followed by an explanation of the file and then, optionally, its modification history:  
  8. 8.      <!‐‐‐     $Id: news.cfm,v 1.7 2003/06/03 21:46:27 scorfield Exp $     Copyright (c) 2008 Presentation Strategies.      Description:         This page renders information about each product.     Parameters:         product ‐ the name of the product family     Usage:         product_page.cfm?product="Flash"     Documentation:         http://sandbox.macromedia.com/wtg/projects/runtime/product_page.html     Based on:         /software/dreamweaver/index.html 1.74 ‐‐‐> Note: We use $Id: $ so that CVS will insert the filename, version and last modified date and author. The explanatory comment for the file should contain, roughly in decreasing order of importance:   a brief Description: of the file, including some kind of classification for components and  custom tags,    a list of Attributes: / method or URL Parameters: / Result: variables with brief descriptions,   Dependencies:, both outward (this file depends on other things) and inward (things known  to depend on, or use, this file ‐ preferably with URLs),   a Usage: example,   the URLs of any known Documentation: for this file,   any files that were used as a basis for creating this file (Based on:),   any files that have in turn used this file as a basis because future changes to this file may  require similar changes to those files (Basis for:). Component Comments The cfcomponent, cfproperty, cffunction and cfargument component tags all have displayName and hint attributes which should be completed for every component, every property, every method (function) and every argument. For cffunction, if the function throws any exceptions, the hint attribute should have "<br />Throws: document any exceptions that the function can throw" at the end of the hint.  
  9. 9.  Put the label text you might show to a business user (on an edit form) in displayName (if  the display name and the actual name are the same, you can omit displayName=).    Put a sentence or two of usage details in the hint attribute. A good, readable style is to  use first person narrative to describe things, e.g., a User cfcomponent tag might have hint="I  represent a user who is browsing the members‐only part of the site", a getName() method in that  component might have hint="I return the full name of this user as Firstname Lastname" and the  argument for the read() method of a UserDAO component might have hint="I am a UUID that  uniquely identifies a user within the membership database". Note: The displayName and hint comments are in addition to the file comment described above.  HTML & XHTML Compliance All generated HTML should be XHTML‐ready:    Lowercase element and attribute names,   All attribute values in quotation marks,   Close all tags correctly, e.g., close <p> with </p> and <li> with </li>,   Although there are rumors that closing empty‐body tags with /> breaks some old  browsers, it is still recommended to do this, e.g., <br /> (note the space before the /),  <img src="..." ... />. Set Dreamweaver to generate XHTML instead of HTML. Generated HTML that is XHTML‐compliant should begin with this: <?xml version="1.0" encoding="utf‐8"?> <!DOCTYPE html PUBLIC "‐//W3C//DTD XHTML 1.0 Transitional//EN"     "http://www.w3.org/TR/xhtml1/DTD/xhtml1‐transitional.dtd"> Some browsers interpret this as strict XHTML so you also need to add the following to the HTML tag: <html xmlns="http://www.w3.org/1999/xhtml"> Do not put the above code in generated HTML that is not XHTML‐compliant! CFML & XHTML Compliance  ColdFusion source code cannot quite be written to be purely XHTML‐compliant because of certain tags (cfif / cfelse, cfreturn, cfset) but you should make an effort to be as XHTML‐compliant as possible. cfelse cannot have a closing tag so it cannot be XHTML‐compliant; cfif and cfreturn do not have an attribute="value" syntax so they cannot be XHTML‐compliant (but cfif has a closing /cfif tag and cfreturn can and should have a self‐closing /); cfset does not in general follow the attribute="value" syntax and these guidelines recommend that for readability you do not quote the value in cfset ‐ but cfset can and should have a self‐closing /. This makes the source code 
  10. 10. more consistent (across CFML and HTML) and will also help you avoid subtle errors such as unterminated nested cfmodule calls. If a simple custom tag invocation is written as XHTML‐compliant, i.e., with a closing />, it will be executed twice as if it were a paired tag with an empty body. This can be surprising at first and cause subtle bugs if your code doesnt expect it! You can guard against this in simple custom tags by enclosing the code with: <cfif thisTag.executionMode is "start">     ... </cfif> Complex custom tags will probably already use thisTag.hasEndTag and have different code executed for thisTag.executionMode is "start" and thisTag.executionMode is "end". All built‐in CFML tags should be written as XHTML‐compliant where possible (cfif, cfelse, cfset and cfreturn are notable exceptions). Table Indentation These are the guidelines for the layout of table source code:   All table tags go on their own lines.   <tr> tags are placed at the same indentation level as their parent <table>.   <td> tags are indented.   The contents of <td> tags may be placed on a separate line and indented, or if they are  short they may be placed on the same line as the <td>.   <table> attributes should be explicitly specified. Example: <table border="0" cellPadding="0" cellSpacing="0"> <tr>     <td>         Table data goes here     </td>     <td>Short text here</td>     <td>         <table>         <tr>             <td>                 Nested table data here             </td>         </tr>         </table>     </td> </tr> 
  11. 11. </table> If whitespace is a problem (e.g., with very long / deeply nested tables), use your judgment to adjust the layout to improve the readability of the code. Given our use of CSS instead of tables for layout, this should be a rare occurrence!  Tag Layout When more than one attribute is passed to a custom tag, each attribute should be placed on its own line and indented. The tag closing bracket (>) should be on a line by itself, indented the same as the matching opening bracket. This allows for long, descriptive names for both the custom tag and its attributes. For very short (single attribute) or relatively short but frequently repeated tags (e.g., cfparam), this is optional. Examples: <cf_my_custom_tag_two     attributeOne="ValueOne"     attributeTwo="ValueTwo"     attributeN="ValueN" /> <cf_my_custom_tag     attributeTwo="Value Two" /> <cf_my_custom_tag attributeOne="Value One" /> <cfparam name="myVar" default="x" type="boolean" /> HTML tags do not need to follow these rules, due to whitespace considerations. ColdFusion Component Layout ColdFusion components should follow the same general rules for layout as other tags. Example: <cfcomponent hint="..." displayName="...">      <cffunction name="doSomething" returnType="string">         <cfargument name="arg" type="string" />          <cfset variables.thing = arguments.arg />         <cfreturn arguments.arg />      </cffunction>  </cfcomponent> An acceptable alternative, using more vertical space, is as follows: 
  12. 12. <cfcomponent hint="..." displayName="...">      <cffunction         name="doSomething"         returnType="string"     >         <cfargument             name="arg"             type="string"         />          <cfset variables.thing = arguments.arg />         <cfreturn arguments.arg />      </cffunction>  </cfcomponent>  SQL/cfquery Indentation The following examples will most effectively describe the preferred SQL indentation standards. Example 1:   SELECT TO.COLUMN_ONE, TT.COLUMN_TWO, TO.COLUMN_THREE FROM TABLE_ONE TO, TABLE_TWO TT WHERE TO.TABLE_ONE_ID = TT.TABLE_TWO_ID AND TT.TABLE_TWO_ID = 10 ORDER BY TO.TABLE_ONE_ORDER_KEY   Example 2 (Insert type A):   INSERT INTO      TABLE_ONE (     COLUMN_ONE,     COLUMN_TWO,     COLUMN_THREE ) VALUES (     ValueOne,     ValueTwo,     ValueThree )  
  13. 13.       Example 3 (Insert type B):   INSERT INTO TABLE_ONE (COLUMN_ONE, COLUMN_TWO, COLUMN_THREE) VALUES (ValueOne, ValueTwo, ValueThree)   Example 4:   UPDATE TABLE_ONE  SET COLUMN_ONE = ValueOne, COLUMN_ONE = ValueTwo  WHERE TABLE_ONE_ID = 10 AND COLUMN_THREE = ValueThree  Application.cfm / Application.cfc  There will be a root Application.cfm or Application.cfc file that provides all the site‐wide core services such as application and session settings, site‐wide constants, form / URL encoding machinery etc. Values can all be set in request scope rather than variables scope to ensure they are available inside custom tags etc.  Each  "application" on the site should have an independent Application.cfm file (containing all the appropriate definitions) or an Application.cfc file. /Application.cfm:   set up application and session settings:  <cfapplication name="<yourAppName>" sessionmanagement="true" .../>   user session setup   process loc= to create request scope language / locale values, as needed   globalization / encoding (always):  <!‐‐‐ Set encoding to UTF‐8. ‐‐‐>  <cfprocessingdirective pageencoding="utf‐8"/>  <cfcontent type="text/html; charset=UTF‐8"/>  <cfset setEncoding("URL", "UTF‐8")/>  <cfset setEncoding("Form", "UTF‐8")/>   include site‐wide and server‐specific constants:  <!‐‐‐ Site‐wide constants ‐‐‐>  <cfset .../> 
  14. 14. <cfset myVar = “bob”> ‐ sets myVar in VARIABLES scope  <cfset REQUEST.myVar = “bob”> ‐ sets myVar in the REQUEST scope  <cfset SESSION.myVar = “bob”> ‐ sets myVar in the SESSION scope  <cfset APPLICATION.myVar = “bob”> ‐ sets myVar in the APPLICATION scope Directory Structure For Applications All ColdFusion code should live in the root folder of the web server application (wwwroot for IIS, htdocs for Apache) and well refer to that as the {cfmxroot} below: {cfmxroot}     <sitename>/            » tree for root .cfm files – e.g. www.mydomain.com        components/   » tree for .cfc files         images/       » tree for image files         includes/           » tree for include files         js/         » tree for .js javascript         style/       » tree for .css files         xml/     » tree for .xml files         <dir...>   » tree for additional .cfm       Performance "Dos" The following are positive recommendations, e.g., "Do xyz..." or "Do xyz instead of...".  Use compareNoCase() for comparing two strings  Use compareNoCase() or compare() instead of the is not operator to compare two items. They are significantly faster. Remember that these functions return 0 if the values match, so they correspond to is not. Example: <cfif compareNoCase(x, "a") neq 0> Not: <cfif x is not "a"> Use listFindNoCase() for OR comparisons Use listFindNoCase() or listFind() instead of the is and or operators to compare one item to multiple items. They are much much faster (order of magnitude for 5+ options). Example: <cfif listFindNoCase("a,b,c", x) is not 0>  Not: <cfif x is "a" or x is "b" or x is "c"> Use arrays instead of lists ‐ in general 
  15. 15. In CFMX, lists suffer from the generally slow string processing in Java which means that list manipulation can be slower than in CF5. In general, it is better to work with arrays of items instead of lists of items: listGetAt() is not an efficient way to work with individual items in a data set! However, see the list vs array caveat in the Dont section below. Use cfqueryparam to increase query performance You can use cfqueryparam to optimize a query that looks something like this: SELECT     * FROM     TABLE_NAME WHERE     COLUMN = #variable# If this query is executed repeatedly with different values for variable then using a SQL bind variable will be faster. cfqueryparam creates these bind variables: SELECT     * FROM     TABLE_NAME WHERE     COLUMN = <cfqueryparam cfsqltype="cf_sql_xxx" value="#variable#"> This allows the optimizer to compile the query once and reuse it every time the query is executed. It is also more secure since it prevents rogue SQL from being passed into a query (because it validates the type of the data). Use blockFactor to increase query performance Adding blockFactor to a query can significantly improve performance. To add blockFactor, examine the data that is being returned. Determine the maximum size (in bytes) of each row. Take that size and determine how many times that number would divide into 32k. That number is your blockFactor, but be aware that the max blockFactor is 100. So, if for example you were getting 200 bytes per row, you could easily fit over 100 rows into the 32k buffer that CF grabs at one time. If you know at runtime that you will have less then 100 rows returned, for example youre writing a query that either returns 0 or 1 rows, do not bother adding the blockFactor attribute. Performance "Donts" The following are negative recommendations, e.g., "Dont do xyz...". 
  16. 16. Dont use evaluate() Avoid evaluate() unless there is no other way to write your code (and there is almost always another way to write your code).  Dont use iif() Always use cfif/cfelse instead of iif(). It is significantly faster and more readable. Dont use structFind() Always use struct.key or struct[key] instead of structFind(struct, key). They are significantly faster and more readable. Dont slavishly convert lists to arrays Even though manipulating an array is generally faster than manipulating a list in CFMX, if you simply need to iterate over a list of items and process each one in turn the faster construct is <cfloop list="#itemList#" index="x"> ... </cfloop>. Dont convert itemList to an array and then loop over that ‐ its not worth it because it probably wont be faster. Dont use cfmodule Its slower than a CFC method invocation, its slower and uglier than using a custom tag with a prefix, its even slightly slower than a regular custom tag invocation. Better options exist: use a CFC (preferred), use cfimport and invoke a custom tag using a prefix (always preferable to invoking a custom tag via cfmodule), or even simply include a file. Dont use incrementValue() Always use x = x + 1 or x++ instead of x = incrementValue(x). It is more readable and slightly faster. Note: In some situations where x + 1 is not legal, incrementValue(x) may be more readable than creating a temporary variable to hold x + 1 and then using the temporary variable. 

×