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 12 (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 6 Andrew Smith
All code in ChiliProject, including comments and variable names, has to be written in English. Use proper grammar and spelling.
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 7 Andrew Smith
h3. Code formatting
152 7 Andrew Smith
153 7 Andrew Smith
Set your editor to use soft-tabs at four spaces for javascript code. Never use actual tab-characters as they will destroy the indentation for users with different tab settings.
154 7 Andrew Smith
155 7 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@).
156 7 Andrew Smith
157 7 Andrew Smith
Try keep source code as readable as possible:
158 7 Andrew Smith
159 7 Andrew Smith
* Use proper indentation.
160 7 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.
161 7 Andrew Smith
* Insert an blank lines between function definitions and two blank lines between class definitions.
162 7 Andrew Smith
* Use whitespace and extra lines whenever needed. "Yes" is the correct answer to the question "Should I add an extra line in here?"
163 7 Andrew Smith
164 7 Andrew Smith
Never use double spaces anywhere else than for indentation.
165 7 Andrew Smith
166 7 Andrew Smith
h3. Syntax
167 7 Andrew Smith
168 7 Andrew Smith
Use @{}@ with all conditionals, even one liners. That way if the code is changed later, the scope is clear.
169 7 Andrew Smith
170 7 Andrew Smith
<pre><code class="javascript">
171 7 Andrew Smith
// Wrong
172 7 Andrew Smith
if (thing)
173 7 Andrew Smith
  doSomething();
174 7 Andrew Smith
175 7 Andrew Smith
// Right
176 7 Andrew Smith
if (thing) {
177 7 Andrew Smith
  doSomething();
178 7 Andrew Smith
}
179 7 Andrew Smith
180 7 Andrew Smith
// Example of why...
181 7 Andrew Smith
if (thing)
182 7 Andrew Smith
  doSomething();
183 7 Andrew Smith
  doSomethingElse(); // This would run even if thing was false
184 7 Andrew Smith
185 7 Andrew Smith
</code></pre>
186 7 Andrew Smith
187 12 Andrew Smith
Define functions using a similar style as "BSD KNF C style":http://en.wikipedia.org/wiki/Indent_style#BSD_KNF_style
188 12 Andrew Smith
189 12 Andrew Smith
<pre><code class="javascript">
190 12 Andrew Smith
function somethingWithArgs(one, two, three) {
191 12 Andrew Smith
    if (foo) {
192 12 Andrew Smith
193 12 Andrew Smith
    } else {
194 12 Andrew Smith
195 12 Andrew Smith
    }
196 12 Andrew Smith
}
197 12 Andrew Smith
</code></pre>
198 12 Andrew Smith
199 7 Andrew Smith
Use @//@ for all comments, @/* ... */@ can be misinterpreted.
200 7 Andrew Smith
201 7 Andrew Smith
Use camel case for variables and function names and capitalized camel case for constructor functions:
202 7 Andrew Smith
203 7 Andrew Smith
<pre><code class="javascript">
204 7 Andrew Smith
// Bad
205 7 Andrew Smith
var the_page;
206 7 Andrew Smith
var ThePage;
207 7 Andrew Smith
var thepage;
208 7 Andrew Smith
var some_function = function() {}
209 7 Andrew Smith
var SomeFunction = function() {} // This implies this is a constructor function...
210 7 Andrew Smith
211 7 Andrew Smith
// Good
212 7 Andrew Smith
var thePage;
213 7 Andrew Smith
var someFunction = function() {}
214 7 Andrew Smith
var ConstructorFunction = function() {}
215 7 Andrew Smith
216 7 Andrew Smith
</code></pre>
217 7 Andrew Smith
218 1
h2. CSS
219 1
220 1
{{html_comment(TODO: CSS coding standards)}}
221 7 Andrew Smith
222 9 Andrew Smith
Set your editor to use soft-tabs at 2 spaces for CSS files. Never use actual tab-characters as they will destroy the indentation for users with different tab settings.
223 9 Andrew Smith
224 9 Andrew Smith
Use the GitHub Styleguide as a reference - https://github.com/styleguide/css
225 9 Andrew Smith
226 7 Andrew Smith
Use hyphens and lowercase for class names:
227 7 Andrew Smith
228 7 Andrew Smith
<pre>
229 7 Andrew Smith
Bad
230 7 Andrew Smith
<span class="aClass anotherBadClass">
231 7 Andrew Smith
232 7 Andrew Smith
233 7 Andrew Smith
Good
234 7 Andrew Smith
<span class="a-class another-good-class">
235 7 Andrew Smith
236 7 Andrew Smith
</code></pre>
237 7 Andrew Smith
238 7 Andrew Smith
CSS classes that are used for JavaScript may be in camel case but try to avoid it.
239 1
240 1
h2. HTML
241 1
242 1
{{html_comment(TODO: HTML coding standards)}}