Coding Standards and Best Practices

General Guidelines

• Do not take the fastest/easiest path to making code work, this almost always results in non-reusable code, take the time to plan it out and do it right the first time. The only time a hack is ever justified is when production is broken, and then it should be fixed on Dev immediately after the production problem is solved.
• Do not place any prototype/trial/test files under the w directories, and do not copy prototype code into the w directories.
• Do not test things using “Save As” dspBlahBlahTEST.cfm, if you need to test something, just check out the file in VSS, change it, and rollback the change if you do not want to keep it.
• Always use the tab key to indent code, never use the space bar for indenting
• Use the “View” function in VSS or windows explorer to view a file, do not check out a file only to view it.
• If you have not made any changes to a file you have checked out, select UNDO check-out, do not check it in
• As a rule of thumb if you have more than 10 files checked out, ask yourself why.
   

• Commenting Your Code:
  Comment any code whose function is not obvious.
  The comment should describe what it is you are trying to do not just reiterate the code. If you are editing a file and find that it doesn't have a comment header please add one to the tag before you check it in.
   
• Client-side Scripting VS Server-side Scripting - The goal is to minimize client-side scripting where possible. Avoiding client-side scripting reduces development, QA, and customer service time because of browser irregularities and client browser settings. Try to limit its use to places where it dramatically enhances the user experience. This is even more important on the public site.
   
• Images and where they need to be saved - Images will be stored in “w/images”. Call an image using #request.appImages#/blah.gif
   
• Write neat code, be anal retentive… it makes it a lot more readable. Nest tags using the tab key. Keep tags lowercase(<cfif> not <CFIF>). As a general rule if a line of code scrolls sideways off the screen you should probably use the return key unless it's an HTML issue like an <a> tag.
   
• Always look for reuse. Yes, it will take you a bit longer to write a reusable object, but every time after that it's less time and the code is much more stable and maintainable.
   
• Always use <cf_location> instead of <cflocation>
   
   

Variables

• Naming Conventions:
  Always error on the side of overly descriptive names. i.e. use variables.femaleUserSearchingForCondoID, not variables.id – this helps prevent name collision in a shared variable space environment like fusebox
  
  All ColdFusion variables must be accompanied by an explicit scope prefix. This will ensure your code uses the intended value and make your code more readable to others. Use the following scopes at all times.
  

  Queries	selTableName.variableName
  Local	variables.variableName
  Request	request.variableName
  CGI	cgi.variableName

  
  Read, but don't create new:
  Client client. variableName – These variables should be restricted to variables used by 90% of all http requests
  
  DO NOT USE:
  URL, Form variables are set to attributes scope in Fusebox, so there's no reason to read them and setting them(outside of an html form or anchor tag) is a bad practice and possibly not allowed in future versions of CF.
  
  Cookies – don't use 'em
  
  Session & Application variables are evil. They reduce server stability and create big headaches as we move to a clustered environment. Please do not create new session variables.
  
  Write all variables in Hungarian notation, i.e. nameOfVariable, not Name_of_variable or Nameofvariable

File and Folder Naming

• CF Templates Location:
  Keeping templates categorized in to function groups keeps code from getting messy. use these file name prefixes when creating new files.
  act - action related templates such as a template that does a switch/case handling or form processing
  dsp - templates for displaying mostly static stuff
  Example:
  www/jameson/worc/dspCreateAccount.cfm
   
• Database Query Files:
  All queries must be located in one of the 4 Query Tag directories. Do not embed any queries in the code itself. This will facilitate reuse and help ensure we don't write the same query 43 times. All files must use the following naming convention: the first three letters is the database action word (select, update, insert, and delete) next is the table name, followed a unique descriptor if necessary. This is used as opposed to the “qry_” standard that doesn't describe the tag's intent. If the query doesn't conform to a specific table, do your best to name it descriptively.
  Example:
          selApplications
          insApplications
          updApplications
          delApplications
  
  The directories that store the queries are under \\chimp\c$\www\JAMESON\w\query\ and a mapping has been added to the cf server to represent this: \wqroot\
  
  Call these files using in case statements using <cfset addToQ(“q.selMetauser”).
  
  Please view the existing files in DB directories for an example of how the tag content should be laid out.

***This is intended to be a living document that benefits all of us, if you have a standard to propose, please bring it up at the next meeting or talk to Mike.