Coding Guidelines

Coding Guidelines

In general, we endeavor to follow the Ruby Style Guide where possible. Another good reference is here. Some additional notes here:

Instance variables

Consider the following quote from Rails Best Practices [1]:

“In partial view, we can use the instance variable directly, but it may be confused and make it hard to reuse anywhere, because we don’t know exactly which instance variable can be used, so use the local variable in partial with explicitly assignment.”

Line Length

Where practical, we prefer to keep lines to 80 characters of length, for the benefit of those on small screens, with split buffers, and also for ease of mailing patches. If there is a compelling reason why a line needs to exceed 80 characters, it is generally acceptable to do so, however.

Where a line has a number of parameters, it is convenient to break them up and indent. Beyond keeping lines under 80 characters, this is easier to read. Consider this (bad) example:

CredentialDefinition.create!(:name => 'password', :label => 'password', :input_type => 'password', :provider_type_id => provider_type.id)

Beyond being well beyond 80 characters, that example can be made easier to read in general if it is rewritten like so:

CredentialDefinition.create!(:name => 'password', 
                             :label => 'password', 
                             :input_type => 'password', 
                             :provider_type_id => provider_type.id)

Where you absolutely need to keep a long chain of methods, Ruby permits you to break lines on a period like so:\

@instances = Instance.apply_filters(:preset_filter_id => params[:instances_preset_filter], :search_filter => params[:instances_search]).
                      list(sort_column(Instance), sort_direction).where("instances.deployment_id" => @deployment.id).
                      paginate(:page => params[:page], :per_page => PER_PAGE)

Note that the subsequent lines are aligned below the initial dot. (Also note that this particular example is actually still too long, but it’s only meant to illustrate breaking lines.)

This page offers some additional feedback on breaking up lines.

Strings and Internationalization

Because not all of Conductor’s users speak English, messages to users (such as flash messages or validation errors) should never be hardcoded in English. Instead, all strings displayed to users should be placed in the en.yml dictionary and then translated accordingly. See the Internationalization page for more detailed guidelines.

Tests

Ideally, tests should be narrowly scoped to test only the relevant portion of the code, with setup handled separately. See Testing DMA for further elaboration.

Other things to fill in

• Other stuff from email
• UI guidelines

References

[1] http://rails-bestpractices.com/posts/27-replace-instance-variable-with-local-variable