Introduction to Clean Code

“There is great power in detail.” —

Robert C. Martin

 

Details — we see them everywhere, don’t we? Though, few people really pay attention to them, at least from what I’ve noticed. Yet still, they have a huge impact, especially if you see them in someone else’s code — their coding style depends on them.

 

I believe the above picture is one of the best visuals of how a bad code is seen by mostly… anyone.
But what is a good code? What does it mean? How is it written? Mostly, what does one understand by clean code?


 

The truth is, as programmers, we will be writting a lot of code through our career. And that is how we express ourselves, by the art of coding — yes, I believe it’s art, it’s our handwritting, even if it’s typed. It’s how others programmers will see us.

But how is a code bad? In my oppinion a code is bad first of all when it isn’t thought through — if you have a slightly ideea of how you are going to solve a problem and you immediately start coding most probably your code is going to be bad.

Why? Because you don’t have it optimized and structured, as every line of code should be. More important than that, you don’t visualize each part of that code, as you should.

  1. Variables

int w;

Lets have the above example. What do you think I want to use that variable for? The weight of an object? Or the width of a square?

int workingDays;

The difference between the two is obvious now and very important. Use one character variables.

Rule: you should (almost) never use one character variables, because they are interpretable

Exceptions: i, j for loops (because they are so common that when seen it is expected that they are used for looping in for conditions).

List diggitsList;

At first you would say this variable is ok, is just right giving the numbers of characters and the meaning. But take a closer look and you will see a 10 points catch.

List diggits<del>List</del>;

Why would you name it diggitsList when it is obviously a list? Also, when you’ll see how it is used (using list typed methods) you’ll know it’s a list. So why repeat yourself? Rule number 2: be concise — don’t repeat yourself, as you shouldn’t.

Another good example would be:

List getListOfBublesTypes; /* see the repetition? */

But how about the number of characters?
If you are a programmer, sure you’ve heard of the 80 characters/line rule, which it’s about that —

Rule: You shouldn’t write longer lines than 80 characters.

Ok, I can agree with that (even if you use  abig monitor chances are: a) not only there might be people using smaller monitors (like notebooks or 11 inches laptops) but also: b) who reads a line of code that has >80 characters? I wouldn’t. But that’s just it? That would mean that the following code is just fine:

list efficientWorkingDaysInAWeekReportedOnAMonthByEmployeeCurrentlyWorkingHere;

Exactly 80 characters (without the indentation). Oh, well… that’s some of a line. Did you read it until the end? No, probably not. Obviously, we shouldn’t abuse by the maximum “acceptable” length of characters — you can see yourself it’s a waste.

I would preffer maximum 50 characters/line, maybe even 40 — that’d be my perfect number — what would be yours?

Lets consider now the following example:

Therefore, I try to use suggestive, yet still short (-ish) variable names, to check all TODOs I have in mind when it comes to clean code.

 

Lets have another example, shall we?

List pairsOfEfficientWorkingDaysAndHoursInAWeek;

versus

List pairsOfEffectiveWorkingDaysAndHoursInAWeek;

Honestly now, have you read the entire name of the variable(s)? Yes, I meant variables, as there are two of them. And yes, there is a difference. Take a look:

List pairsOfEfficientWorkingDaysAndHoursInAWeek;
List pairsOfEffectiveWorkingDaysAndHoursInAWeek;

As you can see above, there is a difference there. Why do that? It just… hurts.

Rule: Choose the same pathern when using variables — especially when using adjectives or adverbs. That’ll make your variables more searchable and also reachable

Plus, would you try searching all the synonyms for a List of efficient <anything>? Probably not. I know I wouldn’t.


 

As I mentioned above about the one single character variables, here is another example of really (really) bad code:

for (l=1; l < I; l++)
{
      if (0 == O)
            o++;
      else
            l += o1;
}

Ew, right? There are (quite a few) text editors in which l (lower L case) and I (upper i case) [this one, too] are very similar (if not even alike). Imagine trying to search for that for loop which you know uses i if it actually uses lower L case — pain and a lot of waisted time.

[Kind of a] Rule: Avoid o, i, O, I, l because they might be confusez with 0 or 1.

  • Lower Camel Case

e.g.: checkingSum, mainPageData;

Rule: For variables, the Lower Camel Case is beeing used in C# (and other languages like Pascal, Java, Microsoft’s .NET, etc.).

 

2. Methods

To be continued… here.

Leave a Reply

Your email address will not be published. Required fields are marked *