#002 - Clean Code - Names

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

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

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

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.

This post is also available on DEV.