Velocity Style Guide

As Velocity is a Java-based template framework, it will likely have content such that the end result will be in another language or structure. Our goal when writing in Velocity is to maintain a high level of clarity in the code and make sure that extraneous whitespace is avoided.

Everyone is free to code however they want, write and follow their own style guides, but if you wish to contribute to SCOOP, please follow these rules:

Formatting

• Use ASCII (or UTF-8, if you have to).

• For any Velocity directive lines, they will all be on their own line

• Make the code very obvious which lines are velocity and which lines are part of the result

• Indentation of Velocity directive lines should contain a Velocity comment block and an appropriate number of spaces. For example:

  #directive
  #**##directive
  #* *##directive

• Use 4 space indents, no tabs in the Velocity comment.

• Use Unix-style line endings. On the last line of the file, too.

• Use spaces around operators, after commas, colons and semicolons, around { and before }.

• No spaces after (, [ and before ], ).

• Indent when as deep as case.

• Use an empty line before the return value of a method (unless it only has one line), and an empty line between defs.

• Attempt to keep lines fewer than 80 characters.

• Avoid trailing whitespace.

Syntax

• Use $!variable whenever possible for soft crashing

• Use &&/|| for boolean expressions, and/or for control flow. (Rule of thumb: If you have to use outer parentheses, you are using the wrong operators.)

• Avoid multiline ?:, use if.

• Avoid line continuation () where not required.

• Never use smalltalk: symbols.

Naming

• Use snake_case for methods.

• Use CamelCase for classes and modules. (Keep acronyms like HTTP, RFC, XML uppercase.)

• Use SCREAMING_SNAKE_CASE for other constants.

• Use self-documenting variable names wherever possible.

Comments

• Comments longer than a word are capitalized and use punctuation.

• Avoid superfluous comments.

The Rest

• Avoid long parameter lists.

• Write such that the end product of the template merge has no trace of the template

  • There should not be extra whitespace or lines in the output

  • Avoid having unhandled variables (They show up as $variable in the result)

• Avoid needless metaprogramming.

General

• Code in a functional way, avoid mutation when it makes sense.

• Keep the code simple.

• Don't overdesign.

• Don't underdesign.

• Avoid bugs.

• Read other style guides and apply the parts that don't dissent with this list.

• Be consistent.

• Use common sense.