Coding Guidelines

Here are the rules of the road for contributing code to the project. Let's follow this process so that we don't duplicate effort and so the code base is easy to maintain over the long haul.

Subversion Repository

The official Subversion repository for Wheels is located at our Google Code site.

Anyone may check out a read only copy of the code using this command:
svn checkout http://cfwheels.googlecode.com/svn/trunk/ cfwheels-read-only

The repository contains a standard SVN structure.

The trunk contains the latest working copy of the project as committed by the project's developers. It may contain bugs and will be in a constant state of flux until it is tagged in a new release.
tags contains official release code.
branches contain any off-shoot efforts that the group has decided to develop independently from the rest of the code.

Core Team Has Write Access

To make sure that we don't have too many chefs in the kitchen, we will be limiting SVN write access to a core team of developers.

At this time, the core team consists of these developers:

Per Djurner
Chris Peters
Peter Amiri
Tony Petruzzi

This does not restrict you from being able to contribute. See "Process for Implementing Changes to the Code" below for instructions on volunteering. With enough dedication, you can earn a seat on the core team as well!

Process for Implementing Changes to the Code

Here's the process that we'd like for you to follow. This process is in place mainly to encourage everyone to communicate openly. This gives us the opportunity to have a great peer-review process, which will result in quality. Who doesn't like quality?

Open an issue in the Wheels Google Code site, outlining the changes or additions that you would like to make.
A member of the core team will review your submission and leave feedback if necessary.
Once the core team member is satisfied with the scope of the issue, they will schedule it for a release and mark your issue as "Approved." This is your green light to start working. Get to coding, grasshopper!
Need help or running across any issues while coding? Run it by the Google Group. They all have opinions and love to let you know all about them. :)
Once we have a unit testing methodology in place, all code will need to have unit tests that validate common and boundary scenarios. Let's run without one until it is announced.
When you have implemented your enhancement or change, use your Subversion utility to create a patch with your changes. Attach the patch to your Google Code issue.
A core team will review unit tests and post any necessary feedback in the Google Code issue.
Once everything is resolved, the issue will be marked as "Fixed." A core team member will then commit your patch to the SVN trunk. He or she will probably also shower you with glory in the Google Group, blog, and/or Community section of the Wheels site.
If needed, open an issue in Google Code to have the additions and changes in your revision documented. You may claim the issue if you'd like to do this, but it's entirely your choice.

Code Style

All framework code should use the following style. This will make things more readable and will keep everyone on the same page. If you're working on code and notice any violations of the official style, feel free to correct it!

Additionally, we recommend that any applications written using the Wheels framework follow the same style. This is optional, of course, but still strongly recommended.

Supported CFML Engines

All code for Wheels should be written for use with Adobe ColdFusion 8 and Railo 3.0.

Naming Conventions

To stay true to our ColdFusion and Java roots, all names must be camelCase. In some cases, the first letter should be capitalized as well. Refer to these examples.

Code Element	Examples	Description
CFC Names	`MyCfc.cfc`, `BlogEntry.cfc`	`CapitalizedCamelCase`
Variable Names	`myVariable`, `storyId`	`camelCase`
UDF Names	`myFunction()`	`camelCase`
Built-in CF Variables	`result.RecordCount`, `cfhttp.FileContent`	`CapitalizedCamelCase`
Built-in CF Functions	`IsNumeric()`, `Trim()`	`CapitalizedCamelCase`
Scoped Variables	`application.myVariable`, `session.userId`	`lowercase.camelCase`
CGI Variables	`cgi.remote_addr`, `cgi.server_name`	`cgi.lowercase_underscored_name`

CFC Conventions

Local variables

Everyone doing OOP with ColdFusion loves all of the the room for error that the var keyword allows! To help eliminate confusion, define a local struct at the top of CFC methods called loc. Any variable whose value should not persist for the life of the CFC instance should be stored in the loc struct.

For example:

<cffunction name="someMethod" access="public" returntype="void">
    <cfargument name="someArray" type="array" required="true">
    
    <cfset var loc = {}>
    
    <cfset loc.someVariable = true>
    <cfloop array="arguments.someArray" index="loc.i">
        <!--- Some code --->
    </cfloop>
    
</cffunction>

CFC Methods

All CFC methods should be made public. If a method is meant for internal use only and shouldn't be included in the API, then prefix it with a dollar sign $. An example would be $query().

Comments

Read and submit questions, clarifications, and corrections about this chapter.

There are no comments for this chapter. Be the first to comment!