Reading Time: 5 minutes

The choice of naming convention. What does it mean?

In Ruby on Rails framework the naming conventions in many cases is imposed. For example, model names must be camel-cased singular word, whereas connected with it database table should have name which consist of lower-cased words connected with underscore sign.

ruby on rails railwaymen clean code ruby on rails railwaymen clean code

You have to assure such naming convention in order to have Rails ORM recognize and use the models, controllers and views you create. However, don’t worry too much about it: in most cases just use tools that Rails gives you — generators — and you will be fine with naming.

Name inside Rails must follow the Ruby programming language naming rules, so you cannot simply name your Rails class starting with small letter, or method name with a big one.

What about other names? Rails will not force you to use any of conventions for variable names inside methods, but nevertheless you shouldn’t choose it arbitrarily. The best decisions might be to use Ruby or Rails style guides conventions, and apply them across your app. Here’s the link to the Ruby guide: https://github.com/bbatsov/ruby-style-guide and to the Rails guide: https://github.com/bbatsov/rails-style-guide

Do you need a code formatting standard?

When it comes to code formatting, it’s always a good idea to stick to some defined rules, whether they are created by community, creators of the programming languages/framework or defined within your company. In any case, following such rules can help to create readable and maintainable source code, that will be easy to work with by creator himself and also others (e.g. teammates).

A different code formatting, especially across a single file, even though it is not harmful for execution of source code (the application will be working exactly the same way with any formatting, as long as syntax is valid) is bad for programmers. A human being tends to recognize patterns and repetitions in his life, and when he/she sees two or more approaches in one piece of information, he will be able to read it, but it certainly won’t be comfortable. For example, one can read a page from some book with inconsistent font size and text decoration, but it will be frustrating, and considerably slower. The same issue will be present for developers dealing with different formatting of the code.

A good formatting standard originates from developers experience collected during his career. It combines the mutual effort to specify, organize and share with others the best practises. Very often — if not always — it embraces the best approaches, better than these chosen by any single one of us. Because of this reasons you really should follow code formatting standards acclaimed by others, or at least use you own/your team rules, when you have a good reason to diverge in some cases. There are some tools that can help you ensure the code quality standards in your project, from which the one the most worth mentioning is Rubocop gem(https://github.com/bbatsov/rubocop). It comes with the set of predefined rules picked up from Ruby on Rails community, but you can easily add your own or edit already present.

Is it worth to use design patterns?

Programming often involves dealing with recurring general problems. Some of the most popular have their example solutions, which are called “design patterns”. Of course, programmer can try to find his own solution, but this often leads to creation of unnecessarily complex workaround, or archiving similar/the same solution, as it is proposed by design pattern. So why reinvent the wheel? Make sure you are familiar with general design patterns, including Object-Oriented Programming ones.

However, using design patterns is not always a silver bullet. There might be cases, when developer trying to apply such solutions will increase increase code complexity, and make some parts of the project far less readable than using another approach.

There aren’t many design patterns you’ll experience while working on Ruby on Rails project, however below is the quick list of top 3 patterns you’ll probably find in most of the bigger RoR projects.

The most popular design pattern in the world of Ruby on Rails is Singleton pattern, often presented in services(objects that combines few models method calls in order to keep your controllers slim). Services tend to use one instance of the object, for example instance of Redis class, for multiple calls across the application. Think about using services next time you’ll think “I really, really need this global variable”.

The second most popular design pattern is probably Decorator. It helps you separate methods used to display information in nice way from methods used for generating HTML or moving logic out from views — helpers. You’ll often find both kinds of methods mentioned above in the helpers, but to keep your code clean you should separate them, because each of them belongs to different layer of the application. There is a great gem called Draper (https://github.com/drapergem/draper) which you can use for that, or you can develop your own solution through the use of Ruby modules.

The last design pattern we would like to mention is Factory. You’ll likely find it in nearly every testing environment through the use of great FactoryGirl gem (https://github.com/thoughtbot/factory_girl). It replaces the traditional YAML fixtures way, present in earlier version of Rails, and helps you create your testing object rapidly. Also, it supports the clean code approach and Rails naming conventions by separating each factory to it’s own file. Also it supports STI approach with the use of inherited factories.

Writing documentation — why is it so important?

Developers very often tends to avoid writing documentation, because they think, it is not necessary. They want to focus on code optimization or writing tests rather than commenting and describing existing application features. This is connected with a strong belief that source code is self-explanatory, that it doesn’t need to have additional characterization — now, and later. Is this a correct attitude?

Programming any piece of software always should involve writing as clear and easy to understand as it’s possible. Ruby on Rails, given it’s Ruby-based nature, helps to archive this goal by friendly syntax and clear expressions. Even though an author think the specific piece of code satisfy these conditions, and understands it, it doesn’t mean it will be true e.g. in a year, or even in a few months, especially when he/she abandon working on the project for some time. In such case any comment, any tiny bit of documentation might be priceless, because of potentially saved time (developer won’t need to analyze step by step what and how given method is doing).

Writing descriptive and readable tests for your application (especially unit tests) also can be considered as part of documentation, because well-written tests provide information how single part of application should behave.

If you end up commenting your code too much it’s about the time to think about the refactoring. However, you need working test suite for that, so be sure to build it first! Here’s a great talk from Cascadia Ruby conferention given by Katrina Owen: http://www.confreaks.com/videos/1071-cascadiaruby2012-therapeutic-refactoring. It will help you to come from big not-well documented method without any tests, to clean code supported by working test suits.

Authors: Paweł, Karol, Sylwia — Railwaymen Team

Protenders banners-1

Recent Posts