Velocity Code Style

Last modified by Lucas Charpentier on 2026/11/04 17:15

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
  • Variables used only inside a Velocity macro should be set in the $macro scope, so that they don't leak out of the macro and overwrite the variables of the calling code. The values a macro returns still go through its parameters, as explained in the previous rule. Example:
    ## Not like this:
    #macro (displayGreeting $userReference)
      #set ($userName = $xwiki.getPlainUserName($userReference))
      Hello $escapetool.xml($userName)!
    #end
    #set ($userName = 'Alice')
    #displayGreeting($xcontext.userReference)
    ## $userName now holds the name of the current user instead of 'Alice'.
    
    ## But like this:
    #macro (displayGreeting $userReference)
      #set ($macro.userName = $xwiki.getPlainUserName($userReference))
      Hello $escapetool.xml($macro.userName)!
    #end
    • This rule applies to new macros and to the macros you modify. When modifying a macro, convert the whole macro, not only the lines you change. Existing macros don't need to be converted otherwise.
    • Convert all the internal variables of a macro at once. Mixing $macro.x and $x for the same variable fails silently: $x is either printed literally or reads a stale global value.
    • The $macro scope is not fully isolated between nested macros: reading $macro.x before setting it returns the value set by the calling macro, if any. Set each variable before reading it, e.g. #set ($macro.x = $NULL).
    • Some variables are already restored by Velocity after the call and don't need the $macro scope, e.g. the macro parameters and the #foreach loop variables. Use common sense for similar cases.
  • 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.

Get Connected