ChiliProject is not maintained anymore. Please be advised that there will be no more updates.

We do not recommend that you setup new ChiliProject instances and we urge all existing users to migrate their data to a maintained system, e.g. Redmine. We will provide a migration script later. In the meantime, you can use the instructions by Christian Daehn.

Code Standards

Version 5 (Andrew Smith, 2012-03-25 04:49 am)

1 1
h1. Code Standards
2 1
3 2 Andrew Smith
{{>toc}}
4 2 Andrew Smith
5 2 Andrew Smith
These are the standard on how code should be formatted and structured in ChiliProject. Always follow these standards when submitting any code.
6 2 Andrew Smith
7 5 Andrew Smith
We recognize that it could make sense to occasionally divert from one of the following rules. Always keep in mind that these rules are in place to allow everybody to quickly navigate every part the code. Thus readability should always be the highest goal when formatting your code.
8 2 Andrew Smith
9 2 Andrew Smith
Every code in ChiliProject including comments and variable names has to be written in English. Use the correct grammar and spelling everywhere.
10 2 Andrew Smith
11 1
h2. Ruby on Rails
12 1
13 2 Andrew Smith
Generally follow the common Ruby and Rails standards. Especially on where to put things. See the following resources for general information about Ruby's coding style:
14 2 Andrew Smith
* "The Unofficial Ruby Guide":http://www.caliban.org/ruby/rubyguide.shtml#style
15 2 Andrew Smith
* "RUBY-STYLE by Christian Neukirchen":https://github.com/chneukirchen/styleguide/blob/master/RUBY-STYLE
16 2 Andrew Smith
17 2 Andrew Smith
The rules stated in this document override rules stated in the above documents if there is a conflict.
18 2 Andrew Smith
19 2 Andrew Smith
h3. Code formatting
20 2 Andrew Smith
21 2 Andrew Smith
Set your editor to use soft-tabs at two spaces for ruby code. Never use actual tab-characters as they will destroy the indentation for users with different tab settings.
22 2 Andrew Smith
23 2 Andrew Smith
Configure your editor to automatically remove trailing whitespace and be sure to leave an empty new-line at the end of file. Always use UNIX line-endings (@0x0A@, @\n@). Don't use windows line-endings (@\r\n@).
24 2 Andrew Smith
25 2 Andrew Smith
Try keep source code as readable as possible:
26 2 Andrew Smith
* Use proper indentation.
27 3 Andrew Smith
* Try to keep line length below 80 chars with a hard limit of 120 chars. Use line continuations for long lines where appropriate.
28 2 Andrew Smith
* Insert an blank lines between method definitions and two blank lines between class definitions.
29 2 Andrew Smith
* Skip parentheses in ruby where it makes sense, that is most calls to things, but never in the declaration of things (see below).
30 2 Andrew Smith
31 2 Andrew Smith
Never use double spaces anywhere else than for indentation.
32 2 Andrew Smith
33 2 Andrew Smith
h3. Syntax
34 2 Andrew Smith
35 3 Andrew Smith
* Avoid the usage of the @return@ keyword. Use it only where absolutely necessary or when it helps to describe the intention (e.g. a @return@ that is deep inside of a nested method). Try to restructure your code first to have a clear flow without breaks.
36 2 Andrew Smith
* Don't use @and@ and @or@. Use @&&@ and @||@ instead.
37 2 Andrew Smith
* On defining methods always use parentheses around the argument specification. Leave no spaces there. Omit the parentheses when there are no arguments.
38 2 Andrew Smith
*Wrong*<pre><code class="ruby">
39 2 Andrew Smith
def foo ( a, b )
40 2 Andrew Smith
  # do something
41 2 Andrew Smith
end
42 2 Andrew Smith
43 2 Andrew Smith
def bar()
44 2 Andrew Smith
  "foobar"
45 2 Andrew Smith
end
46 2 Andrew Smith
</code></pre>*Correct*<pre><code class="ruby">
47 2 Andrew Smith
def foo(a, b)
48 2 Andrew Smith
  # do something
49 2 Andrew Smith
end
50 2 Andrew Smith
51 2 Andrew Smith
def bar
52 2 Andrew Smith
  "foobar"
53 2 Andrew Smith
end
54 2 Andrew Smith
</code></pre>
55 2 Andrew Smith
56 2 Andrew Smith
When naming variables, use self-describing names. Use abbreviations sparingly and only when its meaning is absolutely clear. There are people from about every culture in the world working on ChiliProject, so be clear.
57 2 Andrew Smith
58 4 Andrew Smith
h3. Hashes
59 4 Andrew Smith
60 4 Andrew Smith
Keep the hash keys tight with no whitespace before or after them. Use one space after each comma.
61 4 Andrew Smith
62 4 Andrew Smith
<pre><code class="ruby">
63 4 Andrew Smith
# Good
64 4 Andrew Smith
{:color => 'blue', :object => @issue}
65 4 Andrew Smith
66 4 Andrew Smith
# Bad
67 4 Andrew Smith
{ :color => 'blue', :object => @issue}
68 4 Andrew Smith
{ :color => 'blue', :object => @issue }
69 4 Andrew Smith
{:color => 'blue',:object => @issue}
70 4 Andrew Smith
</code></pre>
71 4 Andrew Smith
72 4 Andrew Smith
Large hashes should be broken up so each key is on one line. This is also useful for hashes that are changed often, git can track a single key change easily since it's on a single line.
73 4 Andrew Smith
74 4 Andrew Smith
<pre><code class="ruby">
75 4 Andrew Smith
# Good
76 4 Andrew Smith
issue_attributes = {
77 4 Andrew Smith
  :subject => 'Code standards',
78 4 Andrew Smith
  :description => 'Bar'
79 4 Andrew Smith
}
80 4 Andrew Smith
81 4 Andrew Smith
# Good, passing a hash style
82 4 Andrew Smith
issue_attributes({
83 4 Andrew Smith
                   :subject => 'Code standards',
84 4 Andrew Smith
                   :description => 'Bar'
85 4 Andrew Smith
                 })
86 4 Andrew Smith
# Bad
87 4 Andrew Smith
issue_attributes = {
88 4 Andrew Smith
:subject => 'Code standards',
89 4 Andrew Smith
:description => 'Bar'
90 4 Andrew Smith
}
91 4 Andrew Smith
92 4 Andrew Smith
issue_attributes = {
93 4 Andrew Smith
  :subject => 'Code standards', :description => 'Bar'
94 4 Andrew Smith
}
95 4 Andrew Smith
96 4 Andrew Smith
issue_attributes = {
97 4 Andrew Smith
                    :subject => 'Code standards',
98 4 Andrew Smith
                    :description => 'Bar'
99 4 Andrew Smith
}
100 4 Andrew Smith
</code></pre>
101 4 Andrew Smith
102 4 Andrew Smith
Avoid trying to line up anything more than the start of the keys. They can look nice but cause the entire hash to be reformatted whenever a key grows. This makes tools like @git blame@ more difficult to use and track what happened.
103 4 Andrew Smith
104 4 Andrew Smith
<pre><code class="ruby">
105 4 Andrew Smith
# Before
106 4 Andrew Smith
issue_attributes = {
107 4 Andrew Smith
  :subject     => 'Code standards',
108 4 Andrew Smith
  :description => 'Bar'
109 4 Andrew Smith
}
110 4 Andrew Smith
111 4 Andrew Smith
# After, notice how the change was to the first key but the second one also had to be changed to be reformatted.
112 4 Andrew Smith
issue_attributes = {
113 4 Andrew Smith
  :subject_was_extended => 'Code standards',
114 4 Andrew Smith
  :description          => 'Bar'
115 4 Andrew Smith
}
116 4 Andrew Smith
117 4 Andrew Smith
</code></pre>
118 4 Andrew Smith
119 2 Andrew Smith
h3. Comments
120 2 Andrew Smith
121 2 Andrew Smith
Use comments to describe what your code is doing, but don't try to write the Great American Novel in a comment or state the obvious like the following comment does.
122 2 Andrew Smith
<pre><code class="ruby">
123 2 Andrew Smith
def add(x, y)
124 2 Andrew Smith
  # Add x and y
125 2 Andrew Smith
  x + y
126 2 Andrew Smith
end
127 1
</code></pre>
128 1
129 3 Andrew Smith
If you need to use more than a few lines of comments, consider refactoring the code into methods that are more descriptive.
130 3 Andrew Smith
131 3 Andrew Smith
If something is unfinished, add a comment prefixed with "TODO".  This will let the rake method of @rake notes:todo@ to find them.
132 3 Andrew Smith
133 3 Andrew Smith
If something needs to be optimized, add a comment prefixed with "OPTIMIZE".  This will let the rake method of @rake notes:optimize@ to find them.
134 3 Andrew Smith
135 3 Andrew Smith
<pre><code class="ruby">
136 3 Andrew Smith
# OPTIMIZE: needs to be speed up, seeing over 30 second delays
137 3 Andrew Smith
def foo(a, b)
138 3 Andrew Smith
  sleep(42)
139 3 Andrew Smith
end
140 3 Andrew Smith
141 3 Andrew Smith
def bar
142 3 Andrew Smith
  # TODO: hardcoded
143 3 Andrew Smith
  "foobar"
144 3 Andrew Smith
end
145 3 Andrew Smith
</code></pre>
146 1
147 1
h2. JavaScript
148 1
149 1
{{html_comment(TODO: JavaScript coding standards)}}
150 1
151 1
h2. CSS
152 1
153 1
{{html_comment(TODO: CSS coding standards)}}
154 1
155 1
h2. HTML
156 1
157 1
{{html_comment(TODO: HTML coding standards)}}