How To “Clean Code”

A long time ago, I read the Clean Code during my first internship. Immediatly after, I started to apply the global idea hidden in this bible for developers. But this task can be quit complicated because it’s too long and the result can end up worst then before. Here are my 4 ideals that I follow in order to apply the Clean Code’s principles without getting lost.

1. Start to define what is the most urgent

The Clean Code gives a lot of little rules to apply in order to provide a beautiful and readable program : Don’t write global functions, Don’t use flags as function parameters, Functions should only be one level of abstraction, and so on… But implement all of them can take a lot of time and require a lot of practice because not all of them are that simple to achieve.

In the ocean of rules that you should use (according to the clean code), I believe that it is important to focus on just some of them at the beginning. The benefit is to achieve a more readable code quicker than expected but also to transform your “most important” rules in automatism faster. 

In my own case, here are my “most important” rules that I focus on every day :

1. Every element of the code should have a meaningful name (file, variable, function, class, …)
2. Max indent per method should be 2 or 3
3. Use Constants
4. Don’t Repeat Yourself

If you noticed, those rules only take care of the readability of the code itself. But choosing to first focus on those do not mean that I don’t try to apply the other rules. It is just my priority.

2. SOLID is difficult, but Single Responsible Principle is the key

The SOLID principles are kind difficult to achieve, especially when the project is big. (Know that the Dependency Inversion Principle gives me nightmares !)

If there is one that is the most important and the easier to use, it surely is the Single Responsible Principle : a class or a function has one and only one responsibility. Refactoring my code this way helps me achieve a more readable code quickly. This is also very convenient for testing. 

3. Don’t lose your mind

This is important for me because I am a perfectionist. But clearly, provide a perfect code is not possible.

First, because it requires too much time.

Secondly, because I can see a code has perfect, meanwhile my coworkers will still be unable to read it. It is my own perception of it.

Finally, because sometime, splitting the code too much makes it unreadable.

Even if refactoring is good, I try not apply each rule literally, because it can have the opposite effect.

4. Don’t forget tests

Last, but not least, you need to clean the tests !

They can be read by any developers to and it is not that hard to refactor them as well. It will be then easier to solve failed test afterwards ;-) .

Et Voilà !

I gave you all of my tricks to help me write better code. Of course it is just my way of doing it, so feel free to adapt those advices to your own situation.

Now, will you excuse me, I have some refactoring to do.

BDD - My Own Specification Sheet

I like to say that I don't have very much time ahead in this project, since my internship is only six months long. On one hand, this short time is not an excuse to skip tests. But on the other hand, I can not spend most of my time writing them. A good alternative for me was then to do some behavior-driven development tests.

Behavior-Driven Development test method allow me to test really important features without making me test every single line of my code. This method helps me create a minimal code that answer a specific need.

To use this method with my Python code, I use behave. Behave is a framework similar to cucumber that allow me to merge my specifications and my tests. This is really powerful since I can now show my tests results to anyone in my project : everybody can understand what is working, and what is not.

Here is a little illustration.

First, I describe my feature just like behave wants me to. I do it myself since my project is specific for my internship, but it can be written by an analyst, a customer, or whoever in charge of those scenarios.

Then, I - the developer - can assign the scenario to the right tests using specific behave tags : @given, @when and @then. It can seem quite annoying to separate those 3 steps, but everything can be store in the context. Also it makes every step reusable for multiple tests !

Behave also provides a lot of different features that can create very particular tests like the concept of "work in progress" scenarios or the use of some step data if needed.

Finally when I run those tests, results are shown in a very understandable way :

Note that the path following the '#' indicate the location of the method associate with the step. It is really useful for refactoring the code and still be able to fix failed tests.