sexta-feira, 26 de junho de 2015

Choosing good names

When we talk about clean code, the first thing that comes to my mind is to give the intent of the code we're writing. When we write some piece of code we want to make it clean, it also means we want to clarify the intent of that unit. Choosing good names for classes, methods, attributes, etc is one way to achieve this. Here is a citation from Robert Martin on Clean Code book:

"Choosing good names takes time but saves more than it takes."

It seems to be something very basic, but many times we're writing code, thinking the names we're giving the Classes/Methods/Attributes are clear enough, and actually it's not that clear. At that moment it seemed that name was the best, the clearer, but if you read that piece of code two or three hours later, you'll probably notice that the name you choose was not transmitting your intent, or at least you will find a better name.

Where there is a comment near a method name for example, It means the author could not reveal the intent of that method. Meaningful names dispense comments.

A classic example is the variables named "a", "b", "c", etc. Here is an example of a method for calculating taxes over a banking transfer:





Once someone who's gonna consume this method looks at its signature, this doubt will appear. What the hell is "a"? What about "b"? Here the developer could have chosen better names for the parameters and even for the method name. Let's express the method intent with well written names:





Now looking at the method signature, it's way clearer. Now the consumer will understand the intent of the method and the meaning of the attributes.

Still there are a lot of other techniques to write clean code and avoid other programmers's suicide when trying to understand what's been written and how to use it.

5 comentários:

  1. Good blog post. Indeed choosing good names is hard, however doing it right will considerable help other people that are reading our code.

    I would add Phil Karlton's famous phrase "There are only two hard things in Computer Science: cache invalidation and naming things"

    ResponderExcluir
  2. Good blog post. Indeed choosing good names is hard, however doing it right will considerable help other people that are reading our code.

    I would add Phil Karlton's famous phrase "There are only two hard things in Computer Science: cache invalidation and naming things"

    ResponderExcluir
  3. I agree. A bit more difficult in Haskell though e.g. I think idiomatically you'd do it like this:

    > calculateTaxOverTransfer :: Double -> Double -> Double
    > calculateTaxOverTransfer = percentage

    The solution might be to use haddock comments though:

    > calculateTaxOverTransfer2 :: Double -- |> Transfer Value
    > -> Double -- |> Tax
    > -> Double -- |> Result
    > calculateTaxOverTransfer2 = percentage

    (Where percentage is a general purpose function created to take the second argument% of the first argument:)

    > percentage :: Double -> Double -> Double
    > percentage amount pct = amount * (pct / 100)

    ResponderExcluir
  4. I agree. A bit more difficult in Haskell though e.g. I think idiomatically you'd do it like this:

    > calculateTaxOverTransfer :: Double -> Double -> Double
    > calculateTaxOverTransfer = percentage

    The solution might be to use haddock comments though:

    > calculateTaxOverTransfer2 :: Double -- |> Transfer Value
    > -> Double -- |> Tax
    > -> Double -- |> Result
    > calculateTaxOverTransfer2 = percentage

    (Where percentage is a general purpose function created to take the second argument% of the first argument:)

    > percentage :: Double -> Double -> Double
    > percentage amount pct = amount * (pct / 100)

    ResponderExcluir
  5. Indeed, good name is must for professional code, I don't allow my developers to commit code without proper names. I also follow these best practices while naming variables in Java programs. They really helps a lot.

    ResponderExcluir