Development Guidelines

This is a collection of principles we adhere to.

General

If you start coding, always start with a git pull origin master. Due to the godlike design of git, you can do that even if you didn't commit or even added your data - just pull it ;) If the Gemfile changed, guard will update your gems and start a development server and a documentation server. We follow the simple principles: Small steps and Red, Green, Refactor (aka. Test/Behavior Driven Development). So, in every of this small steps, always follow these steps:

• Write a Specification in Mini::Test for the functionality you want to implement, make sure it fails (Red)
• Write your functionality along with the documentation, so your test goes Green
• Refactor now
• Now do a commit. If your code resolves or is otherwise connected with a ticket, don't forget to specify that in your message. Any way: Write about what you did in your commit message. That's like uber important.

Another important principle of our development is Fat Models, Thin Controllers, this guideline gives huge flexibility and more readable code - so put everything possible into the model. But NEVER hurt MVC. No HTML/HAML in the Model and Controller. Period.

We use Bottom-Up development, so create the models first. The big advantage is, that you can create the view with Formtastic now automatically.

Models & Migrations

When you want to create a model, always use the following rails command:

rails g model NAME ATTRIBUTE:TYPE ATTRIBUTE:TYPE...

This will generate your model and the migration. If you have an existing model that you want to change in some way, use the following rails command:

rails g migration NameOfMigrationInCamelCase ATTRIBUTE:TYPE

If you choose a name beginning with Add, your attribute will be added, if you choose Remove, the attribute will be removed. Make use of this really expressive syntax. More Information

Wether you create a new model or modify an old one, use

rake db:migrate

to update your database and scheme file! If you add attributes to a model, always think about data validity. Here you will find a lot of Validators like validate_presence_of, validates_uniqueness_of or validates_format_of that will help you to make all datasets complete and valid.

• Model is responsible for data integrity, so use the buildin methods provided for that purpose. There is a nice Ruby on Rails Guide about it.
• Sometimes it is quite useful to generate models without a database connection. Don't use rails g model for that, just create a file with the according name (user.rbfor model User) in the model folder. Don't inherit from any class and you'll be fine.

Controller

They should really be thin. So: Check your parameters (and set a "Not Found" or redirect if necessary). Check if the user has the permissions to do the action. Get your data from the models, and save them in instance variables. Now call render (or, if everything's standard, let rails handle that for you). That's basically everything your controller should do, plus - if later necessary - switch between different output formats like HTML, JSON or XML.

Views (including JS & SASS)

• We use HAML instead of ERB/HTML -- the File Extension is .haml
• We use SASS (Indented Syntax) instead of CSS -- so we use the file-extension .sass
• We use CoffeeScript instead of JavaScript -- so we use the file-extension .coffee. We use the jQuery + jQuery UI Frameworks.

Always remember MVC. Only use variable insertion and simple loops (for array variables). Don't get fancy with clever code. We follow Clearness over Cleverness.

Documentation

For better Documentation, we use the YARD Tool instead of the Standard RDoc. The Syntax is awesome and we are able to automatically publish our Documentation to rubydoc.info, even exporting UML diagrams is possible. YARD lets us choose between Markdown and Textile for Markup, we choose Markdown. Please make heavy use of Yardoc tags - a short introduction is here While you are developing, guard will run a Documentation Server on localhost:8808 for you. The Server will reload on every request, so you can watch your documentation growing while you are coding.

Creating Routes

Creating Routes is a really important topic. They should be chosen wisely when going into production, because people will bookmark the pages and google will index them - so changing should be done really rarely. If you have to change a route, always think about creating redirects for the old route. People and Searchbots love readable routes like /post/about_dwarves instead of /post/12341 - always prefer those. This is simply done by overwriting the to_param method of the given model. More information about routes can be accessed here.