Xabier Garrote

I am going to start writting my first post about the famous book Clean Code. I am going to quote the most interesting parts.

The book starts speaking about the experience of the author with some work stories. Then he ask the question what is clean code?

Bjarne Stroustup the inventor of C++ says:

I like my code to be elegant and efficent. The logic should be stairghtforward to make it hard for bugs to hide, the dependencies minimal to ease maintenance, error handling complete according to an articulated stategy, and performance close to optimal so as not tempt people to make the code messy with unprincipled optimizations. Clean code does one thing well.

Dave Thomas and Andy Hunt authors of The Pragmatic Programmer says:

A building with broken windows looks like nobody cares about it. So other people stop caring. They allow more window to become broken. Eventually they actively break them. They despoil the facade with graffiti and allow garbage to collect. One broken windows starts the process toward decay.

In software industry 80% or more of the work of a developer called “maintenance”. The act of repair bugs.

The Japanese people have a one philosofy called 5S principles. It comprises these concepts:

• Seiri: Or organization (like “sort” in English).
• Seiton: Or tidiness (think systematize in English). A place for everithing and everithing in its place.
• Seiso: Or cleaning (think shine in English). Keep the workplace free of hanging wires, grease, scraps and waste.
• Seiketsu: Or standardization. The group agrees about how to keep the workplace clean.
• Shutsuke: Or discipline. This means having the pracitces and to frecuently reflect on one’s work.

Netiher architecture nor clean code insist on perfection, only on honestly and doing the best we can.

There are 2 parts to learning craftsmanship: knowledge and work. You must gain the knowledge of principles, patterns, practices, and heuristics that a craftsman knows, and you must also grind that knowledge into your fingers, eyes, and gut by working hard and practicing.

You can teach the physics or riding a bicycle. Indeed the classical mathematic is relatively straightforward.

Gravity, friction, angular momentum, center of mass, and so forth, can be demonstrated with less than a page full of equations. Given those formulae I could prove to you that bicycle riding is practical and give you all the knowledge you needed to make it work. And you’d still fall down the first time you climbed on that bike.

Some people are hoping that one day we will discover a way to create machines that can do what we want rather than what we say. These machines will have to be able to understand us so well that they can translate vaguely specified needs into perfectly executing programs that precisely meet those needs.

Use Meningful Names

It is easy to say that names should reveal intent. What we want to impress upon is that we are serious about this. The name of a variable function or class, should answer all the big questions.

• Why it exists?
• What is does?
• How it is used?

Have a look at this example:

int d; // elapsed time in days

The name d reveals nothing. It does not evoke a sense of elapsed time, nor of days. We should choose a name that specifies what is being measured and the unit of that measurement

   int elapsedTimeInDays;
   int daysSinceCreation;
   int daysSinceModification;
   int fileAgeInDays;

Use Pronounceable Names

Humans are good at words. A significant part of our brains is dedicated to the concept of words. And words are, by definition, pronounceable. It would be a shame not to take advantage of that huge portion of our brains that has evolved to deal with spoken language. So make your names pronounceable.

   class DtaRcrd102 {
     private Date genymdhms;
     private Date modymdhms;
     private final String pszqint = ”102”;
      /* … */
   };
   /*Compare to this*/

   class Customer {
     private Date generationTimestamp;
     private Date modificationTimestamp;;
     private final String recordId = ”102”;
     /* … */
   };

Avoid Encodings

We have enough encodings to deal with without adding more to our burden. Encoding type or scope information into names simply adds an extra burden of deciphering.

You also don’t need to prefix member variables with m_ anymore. Your classes and functions should be small enough that you don’t need them. And you should be using an editing environment that highlights or colorizes members to make them distinct

 public class Part {
     private String m_dsc; // The textual description
     void setName(String name) {
       m_dsc = name;
     }
   }
   _________________________________________________
   public class Part {
     String description;
     void setDescription(String description) {
       this.description = description;
     }
   }

Avoid Mental mapping

This is a problem with single-letter variable names. Certainly a loop counter may be named i or j or k (though never l!) if its scope is very small and no other names can conflict with it. This is because those single-letter names for loop counters are traditional. However, in most other contexts a single-letter name is a poor choice; it’s just a place holder that the reader must mentally map to the actual concept. There can be no worse reason for using the name c than because a and b were already taken.