Code Standards¶

Contents

• Code Standards
  • Ruby on Rails
    • Code formatting
    • Syntax
    • Hashes
    • Comments
  • JavaScript
    • Code formatting
    • Syntax
  • CSS
  • HTML

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.

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
• RUBY-STYLE by Christian Neukirchen

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

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.

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

  1def foo ( a, b )
  2  # do something
  3end
  4
  5def bar()
  6  "foobar" 
  7end
  

  Correct

  1def foo(a, b)
  2  # do something
  3end
  4
  5def bar
  6  "foobar" 
  7end
  

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.

Hashes¶

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

1# Good
2{:color => 'blue', :object => @issue}
3
4# Bad
5{ :color => 'blue', :object => @issue}
6{ :color => 'blue', :object => @issue }
7{:color => 'blue',:object => @issue}

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.

 1# Good
 2issue_attributes = {
 3  :subject => 'Code standards',
 4  :description => 'Bar'
 5}
 6
 7# Good, passing a hash style
 8issue_attributes({
 9                   :subject => 'Code standards',
10                   :description => 'Bar'
11                 })
12# Bad
13issue_attributes = {
14:subject => 'Code standards',
15:description => 'Bar'
16}
17
18issue_attributes = {
19  :subject => 'Code standards', :description => 'Bar'
20}
21
22issue_attributes = {
23                    :subject => 'Code standards',
24                    :description => 'Bar'
25}

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.

 1# Before
 2issue_attributes = {
 3  :subject     => 'Code standards',
 4  :description => 'Bar'
 5}
 6
 7# After, notice how the change was to the first key but the second one also had to be changed to be reformatted.
 8issue_attributes = {
 9  :subject_was_extended => 'Code standards',
10  :description          => 'Bar'
11}
12

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.

1def add(x, y)
2  # Add x and y
3  x + y
4end

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.

 1# OPTIMIZE: needs to be speed up, seeing over 30 second delays
 2def foo(a, b)
 3  sleep(42)
 4end
 5
 6def bar
 7  # TODO: hardcoded
 8  "foobar" 
 9end

JavaScript¶

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.

Syntax¶

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

 1// Wrong
 2if (thing)
 3  doSomething();
 4
 5// Right
 6if (thing) {
 7  doSomething();
 8}
 9
10// Example of why...
11if (thing)
12  doSomething();
13  doSomethingElse(); // This would run even if thing was false
14

Define functions using a similar style as BSD KNF C style

1function somethingWithArgs(one, two, three) {
2    if (foo > bar) {
3
4    } else {
5
6    }
7}

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

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

 1// Bad
 2var the_page;
 3var ThePage;
 4var thepage;
 5var some_function = function() {}
 6var SomeFunction = function() {} // This implies this is a constructor function...
 7
 8// Good
 9var thePage;
10var someFunction = function() {}
11var ConstructorFunction = function() {}
12

CSS¶

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

Use hyphens and lowercase for class names:

Bad
<span class="aClass anotherBadClass">

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

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

HTML¶