Variables and Naming Conventions

At work I (with heavy input from the rest of the team) am writing these guidelines for our development practices, so that everyone is working 'on the same page.' I will share this series here for others who may want to know how some folks do it.

Variables. They define the data within our applications. Hard to peg down within our system, with thousands of variables over thousands of files. For this reason, it is time to define proper variable declaration.

Variable naming conventions and scoping can be very different in different programming languages. Within ColdFusion variables are case insensitive, whereas in most others proper case is critical. With the wide mix of languages used here (XHTML, CSS, ActionScript, JavaScript, etc.) we will take the stance that all variables, across all platforms, should remain case specific unless explicitly necessary to change. A camel case approach should be used, with the first letter of the first word (or one word) of a variable remaining lower case, while any subsequent word is capitalized. i.e.: oneVariable, anotherVariable, stillAnotherVariable. (Functions should capitalize each word) You may also employ Hungarian Notation to further identify the type of a variable, if you wish, but it won't (at this time) be required.

Another important action with variables is declaring, and referencing them, from their proper scope. In ColdFusion, you could reference most variables without identifying the scope, but to do so would cause unnecessary load on our systems. When a template is processed by ColdFusion, if the scope is not identified then the server will search through each scope separately until the variable is found. Not only does this cause the system to overwork, but you also run the risk of the system discovering a variable of the same name within a higher scope of the search tree. By expressly referencing all variables by their scope you eliminate these possible issues within our system. Also (within ColdFusion) all scope names should be listed in all uppercase. i.e.: FORM.strUserName, SESSION.intUserID, URL.intStartRow.

Flash

Although they've been used in the past, _global and _root scopes should only be used cautiously. As we integrate more of our tools into each other, these scopes can easily cause problems. Local Variables should be used in functions when possible.

Adobe has a detailed document on best practices on using scope in ActionScript.

Use variable/instance names that describe the functionality of the the item being named. Append an underscore then the ActionScript abbreviation for the type or variable or instance when appropriate. This will make code hinting available in the Flash IDE. For example, next_btn, or submitForm_lv

Use anonymous functions when appropriate, so as not to clutter the code with named trivial functions. Example:

view plain print about
1/*Not this way:*/
2function nextButtonPress(){
3 timeline.nextFrame();
4}
5next_btn.onRelease = nextButtonPress;
6
7/*Rather, this way:*/
8next_btn.onRelease = function(){
9 timeline.nextFrame();
10}

Database Architecture

Table Names

Table names should be camel case, but with the first letter capitalized as well. Table names should not be the pluralized form of what it stores. Example: ProductItemDetail

Linking or Lookup tables which serve as a relationship between a Many-to-Many should include the word Map in the name, preferrably at the end. Example: ProductItemCategoryMap

Column Data Types

  • boolean: Boolean values are stored in bit columns, and have historically been named bVerbWhatever, for example bIsCertified.
  • foreign keys: Foreign key column names should be fkTableName, for example fkProductItemDetail.
  • hex color: Hexadecimal colors are stored in char(6) fields.
  • All fields that store numeric data should be of datatype INT(4) except for very special circumstances.

SQL

SQL keywords should appear in ALL CAPS. Tables should be aliased. For example:

view plain print about
1SELECT        PID.displayName,
2                        PID.description
3FROM            ProductItemDetail PID WITH (NOLOCK)
4WHERE        PID.ID = #arguments.itemDetailID#

All Joins should be specified in the FROM clause. For Example:

view plain print about
1SELECT PI.Make, PICM.Price
2FROM ProductItem PI WITH(NOLOCK)
3INNER JOIN ProductItemCategoryMap PICM WITH(NOLOCK) ON PI.fkItem= PICM.fkItem

There are, always, exceptions to the rules. Typically these exceptions are due to the rules of another language. For instance, within XHTML all tag names, attributes, and attribute values are always lower case. The exception to that rule is anything calling a script function (like the event actions) where case is defined by the JavaScript itself (which is case sensative).

Examples:

view plain print about
1<!--- ColdFusion variables --->
2<cfset VARIABLES.strNextPage = "myNextPage.cfm" />
3<cfparam name="URL.intRowStart" default="1" />
4
5<cffunction name="GetNextPage" access="public" output="false" returntype="string">
6    <cfreturn VARIABLES.strNextPage />
7</cffunction>
8
9/*Flash variables*/
10
11selectedElements = {};
12
13propCount = function(obj){
14    var count = 0;
15    for (var i in obj){
16        count++;
17    }
18    return count;
19}
20
21delete_btn.onRelease = function(){
22    if (propCount(selectedElements) == 0){
23        this._parent.error_mc._visible = true;
24    } else {
25        this._parent.error_mc._visible = false;
26        deleteElements(selectedElements);
27    }
28}

Comments

At work I (with heavy input from the rest of the team) am writing these guidelines for our development practices, so that everyone is working 'on the same page.' I will share this series here for others who may want to know how some folks do it.

First and foremost is documentation. We have an extremely large system, currently made up of nearly 7,000 ColdFusion, XML, Javascript, Cascading Style Sheet, ActionScript, and Flash templates. The original authors of these templates were spread fairly thin, working a variety of tasks while attempting to produce a usable product base to build our company upon. Because of this a large majority of our system is completely un-documented. Now, as a matter of standard practice, every template touched by a developer is given, at minimum, a document header comment to create some form of initial documentation.

[More]