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
What about you? What compels you to write docs?