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 10 (Andrew Smith, 2012-03-25 04:49 am) → Version 11/13 (Eric Davis, 2012-03-25 04:49 am)

h1. Code Standards

{{>toc}}

These are the standard on how code should be formatted and structured in ChiliProject. Always follow these standards when submitting any code.

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.

All code in ChiliProject, including comments and variable names, has to be written in English. Use proper grammar and spelling.

h2. Ruby on Rails

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:
* "The Unofficial Ruby Guide":http://www.caliban.org/ruby/rubyguide.shtml#style
* "RUBY-STYLE by Christian Neukirchen":https://github.com/chneukirchen/styleguide/blob/master/RUBY-STYLE

The rules stated in this document override rules stated in the above documents if there is a conflict.

h3. Code formatting

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.

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@).

Try keep source code as readable as possible:
* Use proper indentation.
* Try to keep line length below 80 chars with a hard limit of 120 chars. Use line continuations for long lines where appropriate.
* Insert an blank lines between method definitions and two blank lines between class definitions.
* Skip parentheses in ruby where it makes sense, that is most calls to things, but never in the declaration of things (see below).

Never use double spaces anywhere else than for indentation.

h3. Syntax

* 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.
* Don't use @and@ and @or@. Use @&&@ and @||@ instead.
* On defining methods always use parentheses around the argument specification. Leave no spaces there. Omit the parentheses when there are no arguments.
*Wrong*<pre><code class="ruby">
def foo ( a, b )
# do something
end

def bar()
"foobar"
end
</code></pre>*Correct*<pre><code class="ruby">
def foo(a, b)
# do something
end

def bar
"foobar"
end
</code></pre>

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.

h3. Hashes

Keep the hash keys tight with no whitespace before or after them. Use one space after each comma.

<pre><code class="ruby">
# Good
{:color => 'blue', :object => @issue}

# Bad
{ :color => 'blue', :object => @issue}
{ :color => 'blue', :object => @issue }
{:color => 'blue',:object => @issue}
</code></pre>

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.

<pre><code class="ruby">
# Good
issue_attributes = {
:subject => 'Code standards',
:description => 'Bar'
}

# Good, passing a hash style
issue_attributes({
:subject => 'Code standards',
:description => 'Bar'
})
# Bad
issue_attributes = {
:subject => 'Code standards',
:description => 'Bar'
}

issue_attributes = {
:subject => 'Code standards', :description => 'Bar'
}

issue_attributes = {
:subject => 'Code standards',
:description => 'Bar'
}
</code></pre>

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.

<pre><code class="ruby">
# Before
issue_attributes = {
:subject => 'Code standards',
:description => 'Bar'
}

# After, notice how the change was to the first key but the second one also had to be changed to be reformatted.
issue_attributes = {
:subject_was_extended => 'Code standards',
:description => 'Bar'
}

</code></pre>

h3. Comments

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.
<pre><code class="ruby">
def add(x, y)
# Add x and y
x + y
end
</code></pre>

If you need to use more than a few lines of comments, consider refactoring the code into methods that are more descriptive.

If something is unfinished, add a comment prefixed with "TODO". This will let the rake method of @rake notes:todo@ to find them.

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.

<pre><code class="ruby">
# OPTIMIZE: needs to be speed up, seeing over 30 second delays
def foo(a, b)
sleep(42)
end

def bar
# TODO: hardcoded
"foobar"
end
</code></pre>

h2. JavaScript

{{html_comment(TODO: JavaScript coding standards)}}

h3. Code formatting

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.

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@).

Try keep source code as readable as possible:

* Use proper indentation.
* Try to keep line length below 80 chars with a hard limit of 120 chars. Use line continuations for long lines where appropriate.
* Insert an blank lines between function definitions and two blank lines between class definitions.
* Use whitespace and extra lines whenever needed. "Yes" is the correct answer to the question "Should I add an extra line in here?"

Never use double spaces anywhere else than for indentation.

h3. Syntax

Use @{}@ with all conditionals, even one liners. That way if the code is changed later, the scope is clear.

<pre><code class="javascript">
// Wrong
if (thing)
doSomething();

// Right
if (thing) {
doSomething();
}

// Example of why...
if (thing)
doSomething();
doSomethingElse(); // This would run even if thing was false

</code></pre>

Use @//@ for all comments, @/* ... */@ can be misinterpreted.

Use camel case for variables and function names and capitalized camel case for constructor functions:

<pre><code class="javascript">
// Bad
var the_page;
var ThePage;
var thepage;
var some_function = function() {}
var SomeFunction = function() {} // This implies this is a constructor function...

// Good
var thePage;
var someFunction = function() {}
var ConstructorFunction = function() {}

</code></pre>

h2. CSS

{{html_comment(TODO: CSS coding standards)}}

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.

Use the GitHub Styleguide as a reference - https://github.com/styleguide/css

<pre><code class="css">
h1 {
font-size: 2em;
color: #f00;
}

h2,
h3 {
color: #0f0;
}

body {
background: #00f;
padding: 10px 30px;
}

.indent-level-1 {
text-indent: 1em;
}

.indent-level-2 {
text-indent: 1.5em;
}

/* this is bad */
p { font-size: 15px }
</code></pre>

Use hyphens and lowercase for class names:

<pre>
Bad
<span class="aClass anotherBadClass">

Good
<span class="a-class another-good-class">

</code></pre>

CSS classes that are used for JavaScript may be in camel case but try to avoid it.

h2. HTML

{{html_comment(TODO: HTML coding standards)}}