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:
/*Not this way:*/
function nextButtonPress(){
timeline.nextFrame();
}
next_btn.onRelease = nextButtonPress;
/*Rather, this way:*/
next_btn.onRelease = function(){
timeline.nextFrame();
}
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:
ProductItemDetailLinking 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:
SELECT PID.displayName,
PID.description
FROM ProductItemDetail PID WITH (NOLOCK)
WHERE PID.ID = #arguments.itemDetailID#
All Joins should be specified in the FROM clause.
For Example:
SELECT PI.Make, PICM.Price
FROM ProductItem PI WITH(NOLOCK)
INNER 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:
<!--- ColdFusion variables --->
<cfset VARIABLES.strNextPage = "myNextPage.cfm" />
<cfparam name="URL.intRowStart" default="1" />
<cffunction name="GetNextPage" access="public" output="false" returntype="string">
<cfreturn VARIABLES.strNextPage />
</cffunction>
/*Flash variables*/
selectedElements = {};
propCount = function(obj){
var count = 0;
for (var i in obj){
count++;
}
return count;
}
delete_btn.onRelease = function(){
if (propCount(selectedElements) == 0){
this._parent.error_mc._visible = true;
} else {
this._parent.error_mc._visible = false;
deleteElements(selectedElements);
}
}
