Coding standards

Important: everyone should adhere to the same standards, and any new code should meet the standards before being checked in. Even if one element or another is mildly annoying to some coders, overall the benefit of having the same standard across the project outweighs that.

A lot of these standards are enforced by Rails and its automatic generation, which is helpful. :)

Table of Contents General Code Formatting OTW-Specific Standards Translations Testing Commenting Database Standards

General Code Formatting

We follow whatever is the most popular convention listed in the Ruby Style Guide.

• 2 space indents
• Generally minimizing parentheses and brackets
• CONSTANTS_USE_UPPER_CASE
• ClassesUsePascalCase
• Note: acronyms should be kept capitalized: MyXMLClass not MyXmlClass
• methods, local_variables, @instance_variables, and @@class_variables all use_lower_case_and_underscores.
• Use curly braces for one-line blocks, use do...end for multi-line blocks.
• If you have any "complicated" arguments to a function, put the parameter list inside parentheses. Stick the open paren of the parameter list up tight against the name of the method. IE, Math.sqrt(2+2) and not Math.sqrt (2+2).

OTW-Specific Standards

Translations

Any string in a view should have the translation function tacked on. That is, instead of:

<h1>Title Of This Page</h1>
<p>Here is your name, <%= user.username -%>.</p>

You should instead have:

<h1><%= ts("Title Of This Page") %></h1>
<p><%= ts("Here is your name, {{name}}.", :name => user.username) %></p>

The "" operators will cause these strings to magically get added to the translation interface, and then as soon as a translation is added, the translation will automatically appear when the user has the appropriate locale set!

Testing

Every piece of functionality should have matching tests in cucumber if at all possible.

Before you fix a bug, create a test to catch that bug, then fix it and check the test now passes.

Run rake cucumber frequently: the sooner you discover you broke something, the easier it is to fix it.

Commenting

Every method should have at least one short comment directly above the function definition. This comment should be edited if the function is changed to reflect that change. EG:

# This cool comment will automatically turn into 
# HTML documentation (when rake app:doc is run).
def awesome_method
  "Look how awesome I am"
end

Database Standards

• All database access should go through Rails and the ActiveRecord models it uses, unless raw SQL is absolutely required.
• A Rails ActiveRecord model corresponds to a table in the database. Every model name should be a singular noun (eg "User" or "Work"), and the corresponding table in the database should be a plural noun (eg "users" or "works"). Use the automatic Rails generators and they will handle this for you!
• We will generally use the term "model" here since you'll be working primarily in Rails. You only need to think about tables if you actually have to manually do work on the database through MySQL.
• Tables which exist solely to join two other tables together are named for the concept or for both tables (an underscore separates words, only the last word should be plural). Mostly you will not need to create these kinds of tables yourself because Rails hides them from you invisibly using the "has_many", "has_one", and "belongs_to" types of relationships.
• Every table will have a numeric column named "id" as its primary key.
• Joins between tables should always use this "id" key.
• If you use another table's primary key as a key in a second model, that column should be named

  [descriptive word]_[first model nonplural]_id

  Eg, if we had a *users* table and a *stories* table ,

  author_user_id

  in the *stories* model would be an author field, which is filled with the "id" field from the *users* model. (The descriptive word is optional but encouraged if any confusion is possible.) This key should always be defined in the database as a foreign key.
• If a length limitation is placed on a text field, that length should be defined on the corresponding model's column in the database.