Velocity code style update

Development
21

Since the discussion died down, I’ll be making a draft page for the proposal. Here is a summary of the opinions above:

1.1. Sentence case comments (## This is a comment.)

  • +1: Marius, MichaelHamann, surli, vmassol (only for sentences)
  • +0: CharpentierLucas

1.2. Multiple single-line comments

  • +1: Marius, MichaelHamann, surli, vmassol (multi-line comment only for javadoc)
  • +1: CharpentierLucas (already in use)

1.3. Issues quoted as ID + TITLE

  • +1: Marius, MichaelHamann, surli, vmassol (id + title)
  • +0: CharpentierLucas (could cause problems when workarounds are spread among multiple files)

1.4. Javadoc comments for large velocity scripts

  • +1: Marius, MichaelHamann, surli, vmassol (multi-line comment, not multiple single line comments)
  • +0: CharpentierLucas (define what larger velocity script means)

1.5. Trailing comments

  • -1: Marius, MichaelHamann, surli, vmassol

2.1. Space delimited = (#set ($a = $b))

  • +1: Marius, MichaelHamann, surli, vmassol, CharpentierLucas

2.2. ${a} only when necessary

  • +1: Marius, MichaelHamann, surli, vmassol, CharpentierLucas

2.3. Space between parantheses (#set ($a = $f.method($c.get($d)) ))

  • -1: Marius, MichaelHamann, surli, vmassol
  • -0: CharpentierLucas

2.3.1. Commas between parameters in macro calls

  • +1: vmassol

2.4. Space between directive and open bracket (#if ($a))

  • +1: Marius, MichaelHamann, surli, vmassol (only for velocity directives, not for defined macros)

2.5. Separate velocity macros for definitions and code

  • 0: Marius, MichaelHamann, surli (best practice, not rule; add new line between macros)
  • 0: CharpentierLucas (only new line, but how to handle when you need to define a macro inside of code?)
  • +0/-1: vmassol (give more examples, there can be cases where it impedes the code)

3.1. Other links

  • +1: CharpentierLucas
  • -1: vmassol

3.2. Meta-style page

  • -1: CharpentierLucas
  • 0: vmassol (more precise proposals)

3.3. New page for velocity resources

  • +1: CharpentierLucas
  • 0: vmassol (more precise proposals)
2 Likes
22

The draft page is completed. Please tell me what you think. You can edit the page directly if you have improvements/fixes. Here is the link again:
https://dev.xwiki.org/xwiki/bin/view/Drafts/Velocity%20Code%20Style

1 Like