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.
Top comments (11)
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 beLoggerContract
.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.
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:
ILog
IWriteToDatabase
IReadFromDatabase
IAuthenticateUsers
IPostComments
For anthropomorphize our interfaces use adjectives:
i feel you
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.