Hello,
Here are some topics which I think should be added to the Velocity coding style, in order to tighten it up (some rules below seem to be used, but with no formal documentation):
1. Comments
1.1. Comments should start with an uppercase letter and end with a dot. Example:
## This macro loops through all users in a wiki.
1.2. Use multiple single-line comments instead of one multi-line comment. Example:
#*
For example don't use this when you have a
multi-line comment.
It could break easily if you delete one character.
*#
##
## Use this instead
##
## Maybe also include the spacing above (title with 1 new line before
## and after, followed by description) as a comment format.
## Maybe add something about when/how to split the text on new lines
## (try to keep the lines under 120 characters, subject and verb on the
## same line, etc.).
## If rule 1.1. is approved, add any exceptions to the dot ending rule.
## (like the title above, or potentially this parenthesis line)
1.3. Quoting issues encountered while developing by id+title or link, so they can be tracked easily. Example:
## This is a workaround for
## XWIKI-12345 : Comments not rendering when in edit mode
## Remove when `github.com/libs/other-library/issues/1234` is fixed.
- Could add a list of regexes to use when searching for issues (like
XWIKI-(\d+)). - Could use a more distinctive format, so one can apply a simple regex to find issues from multiple sources (maybe
[{|ISSUE:Title|}]).
1.4. Add a Javadoc-like description for larger velocity scripts, so the intent and purpose of the page/code is made clear. (same format as 1.2.)
1.5. Should we have a rule about trailing/space-alligned comments (as in the example below at 2.2.)?
2. Code
2.1. Assignments should be space delimited (so not #set ($a='1234'), but #set ($a = '1234')).
- This is already visible in the examples but it might not hurt to say explicitly.
2.2. Only use the ${variable} form where necessary for the code to compile. Example:
#set (${a} = ${b}) ## Don't do this
#set ($a = $b) ## when this does the same thing.
2.3. If an assignment contains function/macro calls, add a space between the arguments and the outer parenthesis.
#set ($discard = $like.this($var.toString()) )
- This could also be applied to other instructions, such as
foreachandif.
2.4. All macros and velocity directives should have a space between the name and the parentheses. Example:
#set ($debugLevel = 1)
#if ($debugLevel > 0)
#foreach ($user in $users)
#myDisplayMacro ($user)
#end
#end
- Note: this seems to disable syntax highlighting for macros, as any construct of type
#word()is highlighted as a macro (even if it doesnāt exist), while#word ()is not (even if it does exist).
2.5. Separate velocity code into definitions and actual code. Example:
{{velocity output="false"}}
#macro (sayHi $username)
Hi ${username|'stranger'}!
#end
{{/velocity}}{{velocity}}
#set ($users = ['A', 'B', 'C'])
#foreach ($user in $users)
#sayHi ($user)
#end
{{/velocity}}
3. Other
3.1. Adding links to any relevant documentation and resources:
3.2. Maybe split some style rules into a separate āmeta styleā page, which could include some common rules between languages. Example:
- using
camelCasefor variable names - max line length (mentioned clearly only in XML code style)
- comments
- issue quoting
3.3. Add other information about writing velocity in XWiki as a new section (or a new page). This way all information about the language is closer together. (This could apply to the rest of the languages aswell). Example:
- Best practices
- Snippet library (maybe a selection of the most common pitfalls/problems)
- Tutorials
- Copyright headers
- Other things in the Development Practices page
Conclusion
Iād love to hear your feedback, or if you have any other ideas!
