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)