Closer to Code

Introduction

This post is a result of recent events with one of the companies that I work with. Sometimes, I help people because I want, sometimes because they pay me, mostly both ;). This time I've been helping one company decide on how to outsource their software development. They have many applications, some of them are old, some of them are younger, they constantly build something new as well - a never-ending story. I didn't want to get into the sole "picking the right company" part of this deal. I was not responsible for financial or any other non-programming part of this process, so instead of recommending companies I focused on something else: How to ensure the same (or better) quality, without having a dedicated team working close to all other people related to a given project.

I've spent some time studying their software, what they do, how they work and what their goals are. Also I've talked with their developers about their feelings and thoughts about all of this. I've spoken to other employees as well, and one thing struck me:

No one really cares! As long as it works, why would they? Programmers didn't have enough time (and sometimes knowledge), project managers didn't care as long as it worked (or also didn't know how to measure things like that), CEO thought that since there are so many apps, it is impossible to do this without a big overhead (and that this would cost a lot of money).

Low quality is just a way to postpone costs that later will be much higher

I can understand why CEOs can think like that. What I don't understand is why project managers and CTOs don't explain this to them. If CEO doesn't care, no one will be able to. And this will turn against everyone one day. Many poorly written projects are hard to give away. The more complicated they are, the more price grows.

Quality always costs. There's no doubt about that. But if you ensure it from the beginning, the further you go with your project the more you will gain. And I'm not talking only about money. Keep in mind, that people don't like other peoples code. And working with poorly written code is what they hate. Low quality equals a much higher rotation rate in teams that have to work with such code. Also keep in mind that everything changes. Programmers change their jobs, some companies are being closed, some are being created, and if you want to outsource stuff, you need to always be aware of that. The only thing that should not change from your perspective is your code quality.

It's always expensive to transfer knowledge and know-how

Outsourcing is not easy. Your team needs to transfer all the know-how to some other places and people. The more code there is, the harder it gets. But what could you do to make it go faster, easier and cheaper?

Ensure code quality!

You could ensure some code and documentation standards across all the firms that will work on your software. That way you can diversify across few that will be able to work with others code. If all of them share same principals, their work quality should be similar, their code should be readable for all of them and you could rotate across those companies according to your business needs. Further more you could even specify in the contract what you expect and what they need to obtain in terms of quality. Programmers will still make mistakes, things will still not work the way you wanted but even then standards will allow other people to fix those issues without any unexpected impact on the whole project. If you set the standards, programmers will have a bit less freedom in how they work and what they do. It's not always good but it is one of those nonfinancial costs you need to take.

Few tools you can use in order to move forward

Some "code related" tools that can help you out with Ruby based software:

Rspec (or any other test framework),
Simplecov,
YARD,
Rubocop.

Rspec (or any other test framework)

This is quite obvious. Tests are must be for any application that we want to maintain. Working with not tested software can be a nightmare. But how to measure tests/specs quality?

Simplecov to the rescue

We could (and we should!) use Simplecov. SimpleCov is a code coverage analysis tool for Ruby.

Picture taken from official Simplecov Github page

It will show you any flaws of your test suites. Not tested classes, methods, cases. It will also generate some useful statistics. If you require usage of this library from your contractors, you can include coverage level as one of parts of your contract. That way they will be obligated to keep tests up and running all the time. Of course they will have to agree on that, because if you force them to use it, they may just write tests that will "pass" Simplecov statistics, delivering you green, low quality tests/specs.

YARD - Yay! A Ruby Documentation Tool

I like self-explaining code. Ruby code can be written both in good and bad way. Unfortunately self-explaining code won't answer all the questions. For example, it won't answer why something is done that way, where there might be a (theoretically) better solution. Also an outsourced code often changes maintainers. None of them will pass all the knowledge to a next one. In cases like that I recommend full YARD documentation. At least on a module/class and public methods level.YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily

Some programmers write comments, some don't. But even if they do, without standardization, it's hard to read and maintain. If you use YARD, none of this will happen. You will end-up with a consistent, standardized documentation that can be viewed both online and offline. You can also easily monitor YARD doc coverage level by running:

yard stats --list-undoc

For example, you may get such result:

Files:          21
Modules:         5 (    0 undocumented)
Classes:        25 (    0 undocumented)
Constants:       8 (    1 undocumented)
Methods:        51 (    0 undocumented)
 98.88% documented

Undocumented Objects:

(in file: app/models/credit_card.rb)

Then it is quite clear that in file credit_card.rb some elements are undocumented and that developers should update docs. As you can see, YARD allows us to easily measure and monitor comments quality.

RuboCop - A Ruby static code analyzer, based on the community Ruby style guide

RuboCop is a Ruby static code analyzer. Out of the box it will enforce many of the guidelines outlined in the community Ruby Style Guide. So, instead of having code written in many ways, you can define a file called .rubocop that will contain all the rules about Ruby code style. That way, you can ensure same standards across many applications/dev teams/companies. It will notify you if anything is not as it should be.

.....C.................................................C......................C......

Offenses:

app/controllers/portal/base_controller.rb:40:3: 
C: Cyclomatic complexity for respond_with is too high. [8/6]
  def respond_with(*resources, &block)
  ^^^
app/controllers/portal/base_controller.rb:40:3: 
C: Method has too many lines. [18/15]
  def respond_with(*resources, &block)
  ^^^
app/controllers/application_controller.rb:52:3: 
C: Cyclomatic complexity for respond_with is too high. [8/6]
  def respond_with(*resources, &block)
  ^^^

Summary

Code quality is really important. It's also a topic for more than a blog post, but I hope you will consider this article useful. Tools that I've presented won't replace good developers but they can help you out omit troubles. If you use them wisely, you can ensure similar code quality in many dev teams.

Background processing is a must-be in any bigger project. There's no way to process everything in a lifetime of a single request. It's such common, that I venture to say that each and every one of us made at least one background worker. Today I would like to tell you a bit about reentrancy.

What is reentrancy

I will just quote Wikipedia, since their description is really nice:

In computing, a computer program or subroutine is called reentrant if it can be interrupted in the middle of its execution and then safely called again ("re-entered") before its previous invocations complete execution. The interruption could be caused by an internal action such as a jump or call, or by an external action such as a hardware interrupt or signal. Once the re-entered invocation completes, the previous invocations will resume correct execution.

So basically it means, that if our worker crashes, we can execute him again and everything will be just fine. No database states fixing, no cleanups, no resetting - nothing. Just re-executing worker task.

How many workers do you have like this? ;) I must admit: I've created non-reentrant workers many times and many times I wish I didn't.

Why our workers should be reentrant and why it's not an overhead to make them like this

Making workers reentrant, especially at the beginning will take you more time than creating a "standard" one. "This will create an overhead" you might think. This might be true but... it's not. If you have many workers that are constantly doing something, and some of them crash, reentrancy will save you a lot of time. It allows you to just fix the issue and rerun tasks again, without having to worry about anything else. Without it, you would spend some time fixing database structure, cleaning things up, performing requests to external APIs from production console and other non-programming related stuff. I guarantee that you will waste much more time doing this, than writing your workers well in a first place.

How to make my workers reentrant?

It's not so hard as you might thing, although sometimes it can be a bit tricky. Of course every worker is somehow unique but there are some general rules that you can use.

Transactional, non-API example test case

The easiest stuff is with non-API, transaction-only workers, that calculate and update some data:

class ScoreWorker
  include Sidekiq::Worker

  def perform(user_id)
    user = User.find(user_id)
    user.update(status: 'calculating')
    # This can take a while...
    user.calculate_score!
    user.update(status: 'calculated')
  end
end

If something would happen when calculate_score! is executed, we would end up with a user with endless "calculating" state. The easiest way to fix this, is to use ActiveRecord::Base.transaction block:

class ScoreWorker
  include Sidekiq::Worker

  def perform(user_id)
    ActiveRecord::Base.transaction do
      user = User.find(user_id)
      user.update(status: 'calculating')
      # This can take a while...
      user.calculate_score!
      user.update(status: 'calculated')
    end
  end
end

If anything goes wrong, we will get back to where we started. Unfortunately this approach has one huge disadvantage: user status is changed in transaction, so until it is committed, we won't have the 'calculating' status (at least if you don't have dirty reads).

Non-transactional, non-API example test case

Approach presented below can be also used to improve previous example. Let's imagine we don't have transactional DB and that every operation is performed separately. We need to catch an exception, rewind everything back and then just reraise error:

class ScoreWorker
  include Sidekiq::Worker

  def perform(user_id)
    user = User.find(user_id)
    # State machine is always nice :)
    user.calculating_score!
    # This can take a while...
    user.calculate_score!
    user.calculated_score!
  rescue e
    # Reset everything so it can be processed again later
    # We "if" in case error was raised in the first line
    user.reset_score! if user
    raise e
  end
end

Of course this will not prevent us from DB failures, but in my experience, workers tend to fail mostly not because of database issues but because of some problems in the app (worker) logic.

Non-transactional, API example test case

What about external API interactions? When we change something remote, we cannot just simply "unchange" stuff. Let's say that we have a charging mechanism, that makes a call (charge) and then it sends an invoice to this user:

class PaymentWorker
  include Sidekiq::Worker

  def perform(user_id)
    user = User.find(user_id)
    Payment::Gateway.charge!(user)
    user.send_invoice_confirmation!
  end
end

How can we provide reentrancy for worker like that? What will happen when user.send_invoice_confirmation! fails? We cannot charge user again for the same month. This means, that we cannot execute this worker task again. We might check whether or not user has been charged:

class PaymentWorker
  include Sidekiq::Worker

  def perform(user_id)
    user = User.find(user_id)
    Payment::Gateway.charge!(user) unless user.charged?
    user.send_invoice_confirmation!
  end
end

or we can delegate invoice sending to a separate worker:

class PaymentWorker
  include Sidekiq::Worker

  def perform(user_id)
    user = User.find(user_id)
    Payment::Gateway.charge!(user)
    EmailWorker.perform_async(user_id, :invoice)
  end
end

In this case, if user.send_invoice_confirmation! fails, we just need to rerun EmailWorker task that will try to send this email again.

Summary

If you want to build systems that are easy maintain and work with - reentrancy is a must be;
Building reentrant workers will save you a lot of time during crashes;
It's not always about transactions - it's more about the state before worker is executed, as long as we can provide same starting point, we can be reentrant;
Reentrancy can be obtained by splitting workers into "atomic" operations that can be rerun;
It's much easier to introduce reentrancy if you use one of finite-state machines available for Ruby;

Page 63 of 170

Ruby programmers/project managers/CEOs Y U NO enforce code quality?

Introduction

Low quality is just a way to postpone costs that later will be much higher

It's always expensive to transfer knowledge and know-how

Ensure code quality!

Few tools you can use in order to move forward

Rspec (or any other test framework)

Simplecov to the rescue

YARD - Yay! A Ruby Documentation Tool

RuboCop - A Ruby static code analyzer, based on the community Ruby style guide

Summary

Ruby (Rails, Sinatra) background processing – Reentrancy for your workers is a must be!

What is reentrancy

Why our workers should be reentrant and why it's not an overhead to make them like this

How to make my workers reentrant?

Transactional, non-API example test case

Non-transactional, non-API example test case

Non-transactional, API example test case

Summary