Velocity Code Style

Spacing & Formatting

• Use 2 spaces for indentation.
• Lines should be at most 120 characters long.
• Velocity directives should have a space between their name and the open parenthesis. Velocity macros calls do not adhere to this rule. Example:

  #if ($someVar)
    #set ($discard = $someVar.someMethod())
  #end
  #myMacro($var)

• Assignment operator should be surrounded with spaces. (See how '=' is written in the example above)
• Velocity macro parameters should be comma separated. Example: #multiParameterMacro($var1, $var2, $var3)

Code

• Use camelCase for variable and velocity macro names.
• Use single quotes for strings that don't need to be parsed/interpreted. This improves performance.
• Use the formal notation(${variable}) only where it is necessary for the code to run correctly. Use the shorthand notation ($variable) as often as possible.
• Capture unused return values of a method call in a variable named $discard, to avoid side effects on the rendered page. Otherwise, unwanted empty lines or the return value will appear in the output. As a result,
  $discard should not be used as a variable anywhere else, since it may be changed without notice. Example:

  #set ($discard = $someVar.someMethod())

• Velocity macros which modify existing variables, or return values through newly defined ones, should have those variables as part of their parameters. This makes it clear which variables will be changed by a velocity macro, better communicating the side effects of a macro call. Example:

  ## Not like this:
  #macro (configureDisplayText $parameters)
    #if ($parameters['user'])
      #set ($displayText = 'user ' + $xwiki.getUser())
    #else
      #set ($displayText = 'unknown value')
    #end
    #set ($userFound = "$!parameters['user']" == '')
  #end
  
  ## But like this:
  #macro (configureDisplayText $parameters $displayText $userFound)
    #if ($parameters['user'])
      #set ($displayText = 'user' + $xwiki.getUser())
    #else
      #set ($displayText = 'unknown value')
    #end
    #set ($userFound = "$!parameters['user']" == '')
  #end

• XWiki 15.10+ Internal macros that are not aiming at being exposed as API should always be prefixed with an underscore (_). API macros should always be properly documented with information on the parameters and a since information. This rule has been introduced with XWiki 15.10RC1, so old macros don't rely on it: they are considered by default as APIs but can be renamed after a vote.

Comments

• Comments should start with an uppercase letter. Sentences (subject and verb) should also end with a dot. Example:

  ## Section list
  #set ($sections = $model.getSections())
  
  #foreach ($section in $sections)
    ## Format the sections in the sidebar using html.
    <div>
      <h1>$escapetool.xml($section.title)</h1>
      <p>$escapetool.xml($section.description)</p>
    </div>
  #end

• Comments which span multiple lines should use multiple single-line comments, not a single multi-line comment. Example:

  #*
  For example don't use this when you have a
  multi-line comment.
  *#
  
  ##
  ## Use this instead when you have a lot of text which doesn't
  ## fit on only one line.
  ##
  ## You can also have empty comments like the line above, in order to aid readability.

• For larger velocity scripts, or whenever the code becomes hard to follow, you should add a comment at the top of the file (following the rules above) explaining what the code does, akin to a javadoc.
• When quoting issues (JIRA, github, etc.), include the issue ID and the issue title, so the comment remains informative even if the external link or issue tracker is down or decommissioned. Example:

  ## Remove when the following issue is resolved:
  ## XWIKI-1234: Issue title does not appear in comments
  ## Also see this:
  ## github.com/external/app/issues/123 - Html not supported inside app