Code Style Guide

Current rules:

• Always use curly braces on if / else statements even if they are just one-liners.

• Avoid lines longer than 120 characters when feasible (one common exception are text strings).

• Put opening curly brace on same line as function, e.g. public void function x() {.

• Put else / else if on same line as curly braces, e.g. } else {.

• local scope replaces the old var loc = {} usage.

• Built-in CFML functions should be CapsCamelCase().

• Use tabs, not spaces for indentation.

• Add newline at end of file (Sublime: ensure_newline_at_eof_on_save": true).

• Trim trailing white space (Sublime: "trim_trailing_white_space_on_save": true).

• Internal functions should be public but start with $, e.g. public struct function $foobar

• No indentation needed after <cfscript> tag.

• Variable assignments should have spaces (e.g. something = x) but not function arguments.

• Arguments with type any should still declare it even though it's the default if left out.

• Do not wrap if / else statements to multiple lines, instead shorten it by assigning variables above it that can be used in the if statement instead (what we allow to wrap are function arguments and struct key / values).

  // Bad:
  if (StructKeyExists(this, "foo") && IsBoolean(this.foo) && this.foo && StructKeyExists(this, "bar") && IsBoolean(this.bar) && this.bar) {
      // ...
  }
  
  // Good:
  local.doTheThing =
      StructKeyExists(this, "foo") &&
      IsBoolean(this.foo) &&
      this.foo &&
      StructKeyExists(this, "bar") &&
      IsBoolean(this.bar) &&
      this.bar;
  
  if (local.doTheThing) {
      // ...
  }

• For clarity, always include a blank line before a comment. (This is the only place where we use blank lines.) The only exception to this rule is when the comment is the first part of an opening block (e.g., first line inside of an if/else if/else, loop, or function block).

  function doSomething(required string greeting) {
    // No blank line needed before this comment because it is the first line of the function.
    local.x = "hello";
  
    // Need a blank line before this comment.
    local.y = "goodbye";
  
    // Comment about the if. Blank line needed because this is a new block of code.
    if (arguments.greeting == local.x) {
        // No blank line needed before this comment because this is the beginning of the `if` content.
        sayHello();
  
        // Blank line needed before this comment.
        return true;
    // Comment about the else.
    } else {
        // No blank line needed here because it is the beginning of the `else` content.
        sayGoodbye();
  
        // Blank line needed before this comment.
        return false;
    }
  }

Internal Documentation

Use JavaDoc style syntax. Public API functions should have a section + category and have descriptions of all parameters.

/**
 * I am the function hint. Backticks replaced with code; tags below get replaced.
 * Tags must appear before arguments.
 *
 * [section: Doc Section]
 * [category: Doc Category] (optional)
 *
 * @argumentName Hint for argument. Backticks replaced with code; [doc: aFunctionName] replaced with link
 */

Proposed Code Example

See the URLFor function for a good example: https://github.com/cfwheels/cfwheels/blob/master/wheels/global/misc.cfm#L575