Blog News about what we are doing

Fernando Dobladez

Why should I care about documentation

Written by Gabriel Andretta

Most of the stuff I’ve read and listened about source code documentation revolves almost exclusively around describing how your code works. It makes it easier for others, or even you, to use it and change it in the future. I believe documentation is much more than that.

Explaining how to use your code will improve your design by validating and increasing your understanding of what it does, and by revealing it weaknesses.

Chances are that if you are not able to put something into words, you don’t fully understand it. It turns out that if there is something weird, funny or complex about your design it will probably be weird, funny and complex to explain.

There are lots of things in our code we can document, and the benefit of each one of those is different.

Let’s take a look to an example.

Class Region
  # Regions for guests
  def self.for_guests
    where(for_guests: true)
  end
end

What I find curious is that while I agree that docs like the one above don’t really add anything, something like the example below does.

# Regions from where guests can make purchases

The extended explanation not only gives the method context and a reason to exists, but it also pops out the question “wouldn’t it be better if we name this method available_for_purchases?”.

What about you? What compels you to write docs?

Share