DEV Community

Cover image for #002 - Clean Code - Names

Posted on

#002 - Clean Code - 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
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

if your code is something like this

int mpd = (n/2)+3
Enter fullscreen mode Exit fullscreen mode

it is better to write it like this

int middle = n/2;
int days = 3;
int middlePlusDays = middle + days;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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

Pronounceable Names

string BMW;
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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


for (TestResult tr : configIssues) {
    Element element = createElement(d , tr);
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (11)

vlasales profile image
Vlastimil Pospichal

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

thinkverse profile image
Kim Hallberg

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

vlasales profile image
Vlastimil Pospichal

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.

Thread Thread
alainvanhout profile image
Alain Van Hout

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.

Thread Thread
vlasales profile image
Vlastimil Pospichal

Interface first, implementation last.

chadgauth profile image
Chad Gauthier

IPretend that the 'I' prefix in interface names acts as an indicator of the action or capability encapsulated by the interface. By adhering to this idea, we anthropomorphize our interfaces, making it easier to understand their roles.

Some examples:

vlasales profile image
Vlastimil Pospichal • Edited

For anthropomorphize our interfaces use adjectives:

  • Logable
  • DatabaseReadable or Database/Readable
  • UsersAuthenticable or User/Authenticable
  • PostCommentable or Post/Commentable
jojonarte profile image
Jojo Narte

i feel you

hyftar profile image
Simon Landry

How would you name your interfaces for dependency injection?

vlasales profile image
Vlastimil Pospichal • Edited

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

sandordargo profile image
Sandor Dargo

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.