Velocity Code Style

This page lists the rules specific to Velocity. The rules common to all the languages used in the XWiki project are on the Code Style page.

Spacing & Formatting

• Use 2 spaces for indentation.
• 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.