loading...
Cover image for #002 - Clean Code - Names

#002 - Clean Code - Names

elkhatibomar profile image Omar ・3 min read

Names

Reveal your Intent

Intent : Nawaya in Arabic

Variables are all around the programm having good names will help read code.

int d; // elapsed time in days

in past documentations were good back in old days , but now it's better to have the variable name is his own comment

int elapsedTimeInDays;

if your code is something like this

int mpd = (n/2)+3

it is better to write it like this

int middle = n/2;
int days = 3;
int middlePlusDays = middle + days;

There is an old mindset that this will cost us more cpu cycles. But we live in a new world where we know now that what matter is code maintainability.

const int ID_NONE = 0; // constant ID for NONE
const int ID_FIRST = 0;// constant ID for FIRST
const int ID_SECOND = 0;// constant ID for SECOND
const int ID_BOTH = 0;// constant ID for BOTH

look at those variable names and comments , what did you understand from this code?

actually name nor comments mean nothing for me as reader.

you will tell me read code this is a shame , I am busy/lazy I don't have time for your bad code.

Avoid Disinformation

disinformation

int tuesday = 1;

look at this expression What you think it mean? Well what I need is to make sure that if today is tuesday

isn't better if we write it like this?

int isTuesday = 1;

this is disinformation i give you an variable that you may miss understand that this is a boolean.

Pronounceable Names

string BMW;

how I need to pronounce this?

How I should understand this? does it mean the bmw car? should I read it like boomwww?

isn't this better?

string BestMatchingWord;

names are the tools to communicate with others , so make sure to express what you are saying well.

Avoid Encodings

Hungurian notation

those are the hungarian Notations , those was usefull back in old days to know what is the type of your variables. But now our IDE is better he can know what is the type of a variable by hovering over it , And our compiler , unit tests will protect us from any type error.

Parts of Speech

your functions should be methods like getTotal() , divide()

structs should be Adjectives like struct COLORS = {...}

your booleans should be descreptive like isUpper() , isLower()

your calsses should be like this class Account not class DATA , class INFO , class MANAGER

The Scope Length Rule

scope

for (TestResult tr : configIssues) {
    Element element = createElement(d , tr);
    rootElement.appendChild(element);
}

tr is a fine name because the scoop where it is declared is small , and had been used directly after his declaration.

but what is not fine is d it is not declared in same scope of it's defenation

d is an instance of a class Document , it is better to call it doc or document.

so in small scope the shorter names are better , but in large scopes bigger are better , so yes size matter :)

While for functions , public functions that are going to be called in many other places outside the class should have small names. Why? the Class have a name example File.Open() Imagine calline File.openFileAndThrowIfNotFound()

and private functions should be long because they are called locally.

Posted on by:

elkhatibomar profile

Omar

@elkhatibomar

Computer Scientist , Full stuck software engineer , Linux user since childhood , Classical computer Science books lover , DevOps in progress...

Discussion

pic
Editor guide
 

Hungarian notation is still alive:
class Logger implements ILogger
I hate the prefix "I".

 

Have you tried the contract naming? Instead of I it would be LoggerContract.

 

No, in my opinion it's bad just the same. I use adjectives derived from the names of the required methods. The interface tells the class what capabilities it must have. Contract tells word contract only, no ability.

Indeed. It's an odd dissimilarity between C# and Java, that in Java it's the interfaces that are typically/often seen as primary: you have a Car interface and a CarImpl class (or rather, a specific type of car). After that, the user of the Car instance should only care about the instance being a Car, not which specific kind of car, apart from what can be gleaned via the interface's methods.

Interface first, implementation last.

 

How would you name your interfaces for dependency injection?

 

It depends on what abilities will be required from the injected object. ILogger is not an ability.

 
 

This is the misinterpretation (not by the author) of the Hungarian notation. If you want to learn more about it, read this article from Joel Spolsky. It was not about types as we mean them.