The 4Cs Rule: Clean Code, Clever Code
Tags: Programming, Web Development, Coding, Development, Clean Code

Much has been written about Clean Code, perhaps the best known book is the one with the same title, written by Robert C. Martin, aka Uncle Bob. But there are also another series of principles and philosophies that help to achieve this: SOLID, DRY, KISS, YAGNI, design patterns…

The responsibility of writing clean code rests with each of us. Your job as a developer is to defend it and evangelize about it. You have no excuses for not doing it. In this article I want to break down the basics to start writing clean code:

Language

In English, please. The control structures (if, else, for, foreach, switch, …), the functions (count, date, die, isset, empty, …) all are in English, therefore for consistency it is advisable that the name of our variables, classes and methods are written in English.

It seems like a no-brainer, but programming in one’s own language is more common than we might believe. It is something that does not affect the operation of the code, but English is a standard, so let’s take it as such and program in English.

Over the years I have come across methods like obtener_usuarios(), even some performance by someone with surprising creativity who is unchecked with methods in Spanglish like: get_usuarios(). Has no sense.

Naming Things

There is a sentence that says: There are only two hard things in Computer Science: cache invalidation and naming things.

And the phrase is very right, naming things is something that may seem trivial, but it is not. It is something very important. Names should reveal intent and be short, clear, explicit, and descriptive.

A name should express what it does just by reading it. It is recommended that you start with a verb (get_, set_, check_, is_, has_), for which you should establish a list of “common” verbs and not get out of there, to avoid inconsistencies due to synonyms (eg: get_, obtain_, receive_ ).

And what about the variables and “magic” numbers? Who has not come across something like $s == 3? What the hell is “s”? “3” what? Put yourself in the shoes that someone new joins the team and comes across something like that, the normal thing is that first they waste time in figuring out what this means, and finally they make you lose it to explain it to them, as long as you remember to what was that…

If instead of the above you find $status === PUBLISH, just by reading it you have a better idea of where the shots are going. I repeat, always use descriptive names, avoid abbreviations and above all avoid “magic numbers or text strings”, better use descriptive constants.

Functions

Ideally, methods or functions you develop should be small and only do one thing. In this way we will comply with the Single Responsibility Principle (SRP). If a method does two things, better divide it into two independent methods.

If a method does only one thing, it will be simpler (we comply with the KISS philosophy), it will be more easily understood, it will be better maintained, and it will be more easily testable, something desirable in any software development.

Kilometric functions or methods with hundreds of lines are a cocoa, they lead to errors and it is necessary to invest a lot of time in understanding them when you have to modify something about them. The more complexity, the more problems.

It is also desirable that they do not receive more than 2 or 3 parameters, and that they return values of the same type. That is, if a method returns an array with the data of a user, in case of not finding results because the user does not exist, it tries to avoid returning a “false”, which is a boolean value.

Use strict_types, it will make your code more robust and stable. If a function receives an array as a parameter and for whatever reason your application calls that method passing it a string, it will cause an error. But it is an error that must be solved, it is an indicator that a method is being misused, and you will be able to correct it.

Classes

As in the functions, its size must be reduced and have a single responsibility, the one indicated by its descriptive name.

For organizational reasons, it is recommended that static constants be declared first, then static variables, then instance variables, and then functions or methods. Of all this, first those that are public and then those that are private.

Classes must comply with the Open/Closed principle, that is, they must be open to extension and closed to modification. If we have to make a new functionality, or carry out an adaptation for a new requirement, it is better to introduce new classes that extend, and not modify the existing one.

Comments

The Clean Code preaches that the code should speak for itself. Comments should not compensate for incorrect code. The code must be so simple and so descriptive that it resembles natural language, therefore it will be easy to understand just by reading it.

Therefore, documentation or comments are not often emphasized, as they would only be justified if we have not been able to express it with the code. BEWARE, it is not advisable not to document, if not to document the bare minimum.

If we have a method called get_user_by_id, I can safely assume that passing an ID to this method will return an object with the user’s data, therefore any additional comments or documentation is probably redundant and over.

Boy Scout Rule

With the passage of time, all developments generate what is known as technical debt.

The Boy Scout rule preaches leaving camp a little better than you are when you arrive.

Applied to development, this rule would advise you that when you are going to make a modification on an existing method or class, take the opportunity to leave it a little better than it was, for example adding more documentation, adding tests, renaming a variable so that it is better understood , simplifying the logic, extracting part of the functionality to other methods to comply with SOLID…

In this way the code will improve over time, in fact continuous improvement can be understood as an inherent part of professionalism.

The Boy Scout rule can be a double-edged sword. If you do not limit the scope of these improvements, you can find yourself involved in a refactoring that eats up your time or the resources assigned to a sprint.

Testing

Protect your code with tests. Tests are your safety net. Who has not happened to have touched something and things that in principle have nothing to do with have stopped working? If you have good test coverage, these types of errors usually tend to disappear.

The tests can be arduous, complex and some developers tend to leave them for the end, and many times you eat the estimated time and in the end they are either not done or less than what would be recommended.

You have techniques, such as TDD, that force you to first create the tests before the code, thereby ensuring that you will carry out a battery of tests before developing the software.

Conclusions

You will notice the benefits of doing clean code from day one, and in the long run you will get a more robust, scalable and maintainable code.

This is just a base, something to start with. I recommend that you search the internet for a lot of information, articles, videos and books about it.