Code Legibility

you write your code to whom?

Not long ago, I participated as a freelancer in a maintenance project on legacy code. Discovering a little about the code, I found this file: views.py. Eight thousand lines with database mode, infrastructure, business rules, validations. Furthermore, the code was terrible, with names without meaning, hidden rules and without documentation.

Who has never seen it before?
So, thinking about this situation, I started questioning myself: the previous developer wrote the code to whom? Maybe while he was coding, what he was writing made sense for him. But to him and who else? In the end, you, the developer,

write your code to whom?

Is it easy to understand what you are trying to express? How much do you care about quality? If you don’t have this kind of preoccupation, you aren’t agile. To me, one of the qualities of being agile is being able to respond fast to changes: so, if you don’t have well written code, you will not be able to respond quickly. Of course, well crafted code alone will not make your project a success; a lot of variables have to be right to have a successful project, but having a nice codebase is a very important part of the development process.

Part of good code comes from the legibility of the code: that meaning how you express, through the code, the ideas that are in your head and in the business rules. It’s not an easy task, but, with some ideas, I believe that nice transformations will happen in your project.

1. Always give good (awesome) names to your variables. From variables and functions to classes, the name of things is the main way to express ideas, so be clear and intuitive. Moreover, do not mix up ideas with types. This just disrupts the flow and doesn’t say anything new.
   Example:
   String nameString = “John”;
   String name = “John”;
2. Minify work: create functions that do only one thing. This is a way to uncouple your code, increase legibility and help to write tests. The smaller the function, the easier it will be to give a name to it ;)
3. See a history happening beyond the code: If this history is confused and hard to understand, something should be refactored. Imagine classes as characters interacting between through their methods.
4. Comments: If you have lots of comments in your code you should be concerned; it can be a signal that the legibility is bad. The code is responsible for telling how and which way things will happen, and if well written why the comment? Moreover, do not leave commented out snippets of code in your project, this only creates doubts in whomever is maintaining your code.
5. Organization is everything: See your code as an API. Show that your actions can happen easily, intuitively and in a way that any developer can understand.

Your code can talk, so, tell a story.