Tuesday, February 9, 2016

Measure your code to make it better



Let's talk about code quality, a subject that should be of interest of all software developers.

Low quality code is a great problem. It may render a system completely useless, if you don't do something about it. Measuring the quality of your code is not an option, it is an obligation. There is no excuse to low quality code nowadays, when we have many tools to help us to detect this.

First of all, we Ruby developers (should) always start by creating tests, not by writing code. This helps a lot when it comes to be sure our code does exactly what is expected of it. If this is a good practice in Ruby, it should also be considered as a good practice for all other languages.

But we most not delude ourselves. When our code passes our tests, it means the code does exactly what is expected of if, but it means nothing more than that. It does NOT mean, for instance, that our code does what is expected of it in the best possible way. Or that it does what is expected of it respecting all criteria for good coding. Or respecting Ruby principles, like DRY.

If we intend to have the best possible code, we must do more than testing. We must measure our code according to certain criteria. This article will discuss ways to do so.

Flog

If you run

$ gem install flog

then you'll have a great tool to measure the complexity of your Ruby code. This gem flog, when run against a piece of Ruby code, uses a technique quite similar to ABC analysis (we'll talk about this some other day, but you may find info about it here) to give you a flog score of your code. It is kind a convention that the flog score of a certain piece of code must be smaller than 20. Anything above 20 indicates your code needs refactoring. Also, anything above 60 will be considered quite dangerous.

To run flog against your User model, just do

$ flog app/models/user.rb

Flay

Avoiding code duplication may be easy if you use the gem flay. You may install it with the command

$ gem install flay

Flay will look for large identical syntax trees to determine where you have code duplication and will tell you if it finds it.

To run fly against your code, just type

$ fly /path/to/your/app

and see the results.

Badges

Consider adding some badges to you project.


These badges are offered by many public and private service, and they are very useful because not all people who will have the time (or patient, by the way) to test your code over an over again. These people need to see immediately if that gem is safe, for instance.

Adding badges indicating your code is building correctly (https://travis-ci.org), the amount of code covered by your tests (https:coveralls.io) and the CodeClimate GPA coeficient (ranging from zero to four) you are helping people to know how safe and sound your Ruby gem is.

  • Build status badge


Visit https://travis-ci.org and signup with GitHub, then add your GitHub repositories. After doing so, all pushes to a repository added there will trigger a complete build of your app. You may get a badge indicating your app is building or not.

I'be seen some developers saying things like "Why should I use a badge saying my app is not building?" or "I'm going to remove the build badge because my app is not running right now. I'll put it back whe the build is fine". You use such a badge even when you break the build because you live in real world. People will know your build is broken even if you don't tell them. And they will know because they will test it and it will fail. And they will not trust your code anymore, because it was broken without a warning.

I'll write an article soon to give some advice about good practices to make Travis build easier. This platform requires some attention to details in order to build correctly your application. Your RSpec tests, particularly, must be written carefully, considering you are now the platform owner and your powers are limited there, specially when it comes to directly accessing the file system.

  • Code coverage badge


This is another good info you may add to your README.md file at GitHub. this badge indicates the rate of your code covered by your tests. the ideal situation would be 100%, but we all know this seldom happens. But it is important to have the highest code coverage rate possible.

To get a badge like this, visit https://coveralls.io, sign up with github and follow the procedures there to start gathering this statistics. 

Then againg, if your code coverage is low, don't try to hide this fact by avoiding the badge information. Right the opposite. Put the badge there and improve your code coverage. The badge is for other people to see, of course, but it is also a warning to you about a bad practice of writing code without writing the corresponding tests beforehand.

I'm telling this to you, but my own badge is not telling me the code coverage, as you may see in the image above. I just don't know what is happening and had no time to investigate this. By the way, if you have a clue to me, post it as a comment in this article or send me by e-mail (edvaldoajunior@gmail.com). I'll thank you a lot.

  • Code Climate badges


I'm using two Code Climate badges. The first one tells me the GPA coefficient of my code, ranging from 0.0 to 4.0, higher values being better than lower values. This metric evaluates complexity, bugs and even your programming style according to Ruby standards.

The second one tells me the number of issues in my code.

To get these badges, visit https://codeclimate.com.

IMPORTANT: This is a commercial service FOR PRIVATE REPOSITORIES. You may sign up for a 15-days free trial, but after this period you'll have to pay to use the service if you intend to use it to measure private repositories. But it is completely FREE for Open Source!

If you google 'metrics for quality of software' you'll probably come out with other tools. What really matters is that you use some kind of metrics to evaluate your code and act accordingly, fixing the problems detected. Your customers will thank you a lot.