Self documenting code is code that speaks for itself. The code becomes an understandable piece of text that tells stories about business objects that interact with each other in various contexts.
We've gathered our team's thoughts about how to make readable code:
Write short methods
If you find methods starting to get longer than 5 lines it's doing too much. Try to shorten it down.
Carefully choosing method names
A method like #inspect is short and simple and perfectly describes what it does. Ruby is full of these kinds of methods:
We've already established (step 1) that the method will do one thing, so name it by what it does. Short and sweet is the goal... Examples:
save_in_background. If a method takes arguments it is possible to take this into account:
In ruby adding a
! to a method tells you the method will modify the object it is called on.
? to any method that returns true or false.
Variables are a way to cheat if you weren't able to find a good name for the method.
@user = GoogleAuthService.call(security_token) Finding the perfect name for a variable is difficult. But it will pay off the next time someone looks into the code.
Use common design idioms
Use Ruby’s opinions on method naming
Reuse method names like call and to_s that developers already understand from ruby. Ruby uses the call method for an executable block of code. That's why it's good practice to use the call method in a service. That way if someone comes along and sees a call method, they can already guess how it works.
Services are a great place to group logical pieces of functionality. In fact, inspecting the services folder of an application should tell the programmer what the application really does, which is not always obvious when looking at controllers or models.
Decorators let you create methods on objects that return data in only the contexts they are needed. The most common place to use a decorator is in the view.
Readability > Optimization
Optimization is great. In databases and other places where it actually makes a difference to response times. Premature optimization: you don't know if it will actually make a difference. Skipping a more verbal series of steps for a few shortcuts might shave off some milliseconds, but it adds minutes to the next time you try debug what you wrote.
Testing code properly will be a guide to future developers when they approach your codebase. They'll get an overview of the flow of the application. The same ideas with improving code readability apply to writing specs!
Focus on contexts in tests. They are useful for separating specific behaviors and conditions in the program’s flow.
The naming in each block is important. When the test fails it will read in a way that makes sense: Failed: Admin dashboard with a new notification displays the notice.
Use language style guides
At Netguru we use automated checking of our style with Thoughtbot's hound which uses rubocop. If that wasn't enough our code reviews not only check code quality but also code readability.
There are style guides for:
Thanks for your tips everyone (including hound)!