Clean Code Series: II

If you haven’t read the previous blog Clean Code Series:I from my blog series please refer to them.

Meaning Full Names Jutsu

Why meaningful Names?

• Consider you are naming a child (sounds easy right)

youAreMyKid(), cuteLittleAmanda(), shyBabyRobAndJanet()

• I guess you would want to consider those names.
• Hope you now consider naming variables, functions and classes.

How to write meaningful names?

These katas (Rules) will let you flex the rationale behind the naming convention. They have been made succinct from Clean Code Chapter 2.

User Intention Revealing Names:

a) int d ; 
b) int days;
c) int elapsedTimeInDays; 

• All variables are intended for the same purpose → describe days.
• I hope you found option (c) more comforting to understand it’s purpose.
• We should always name variable to make it easier to understand and reveal the purpose of it.

Avoid Disinformation:

• We should avoid using standard Java Keywords in names unless it refers to it.

List accountList; 
Naming is good unless it's a Java List.

• Using name which vary in small way.

User user;
Users users;
// Both are valid but creates ambiguous as to what they refer.

• Using letters ‘O’ and ‘l’ similar to number ‘0’ and ‘1’.

Make Meaningful Distinctions:

• The name should be distinct and should make it meaningful.

ProductInfo and ProductData; // Are they related or similar, can't be distinguished
getActiveAccounts(), getActiveAccount() and getActiveAccountInfo() // Can't get any meaningful distinction whenever we need to use it, we have to look at the function what it does to understand it

• Remove redundant noise words.

String nameString; // Name can't be other than string, hence noise added

Use Pronounceable Names:

• Don’t include acronyms unless otherwise a universal one.

private Date genymdhms --> This may be a generation (date,year month,day, hour, minute and second) TimeStamp since it is company specific acronym. But, doesn't make sense.

Use Searchable Names:

• Use single name not single letter for local variables.

int d; // One might name local variable as just letter
int t; //
int workedDay; // This looks more readable
int realTask;

• Use numeric constant to define constants in class, so that 5 or 24 wouldn’t be ambiguous.

int WORK_DAYS_PER_WEEK = 5;
int HOURS_IN_A_DAY = 24;

• Consider the following for-loop:

for (int j = 0; j < 34; j++) {
   s += (t[j] * 4)/5;
}
// Did you understand what the loop is doing??

for (int j=0; j < NUMBER_OF_TASKS; j++) {
  int realTaskDays = taskEstimate[j] * realDaysPerIdealDay;
  int realTaskWeeks = (realdays / WORK_DAYS_PER_WEEK);
  sum += realTaskWeeks;
}
// Hopefully I don't have to explain what it's doing now

Avoid Hungarian Notations:

• Java is type-rich system, that enforces types.

String mName; // Even- though Android specifies it's usage
int sDayCount; // avoid Hungarian notations

Special Case of Interfaces and Implementations

• Interface and it’s implementations can be exempted from prefixes and hungarian notation.

IShapeFactory factory;
ShapeFactoryImpl shapeFactory;

Class Names

• Class and objects should have noun or noun phrase names.

Customer, WikiPage, Account, AddressParser

• Avoid Class name as verbs.

Manager, Processor, Data, Info

Method Names

• Method name should have verb or verb phrases

postPayment(); deletePage(); save();

• Accessor and mutators and predicators should be named for their value and prefixed with get, set and is.

getName(); setName(); isPosted();

Don’t be Cute with Names

• Don’t be clever with naming.

HolyHandGrenade, whack(), eatMyShorts()

Pick One Word per Concept

• A consistent lexicon should be followed.
• We might easily mix the following as equivalent word for similar methods.

fetch, retrieve and get --> Represent similar meaning
controller, manager and driver --> Can be used interchangeably

Use Solution Domain Names

• Whenever possible use CS terms, algorithms names, pattern names, math terms for naming.

AccountVisitor, JobQueue,

Add Meaningful Context

• There may be variables that are meaningful in themselves. But, they may be referring to a higher context.

firstName, lastName, street, houseNumber, state, zipCode.

• Here these variables are individually correct but they represent a bigger context that is the billing address.
• In this case, extracting them to a single Class Address would represent the bigger context.

Don’t Add Gratuitous Context

• Your company might be eager on using acronyms for everywhere possible, eg GSD for “Gas Station Deluxe”.
• Don’t add gratuitous context to every class possible.

GSDAccountAddress, GSDPhoneNumber, GSDEmployee.

Well these are conventions after all, nobody cares much.

Thanks for bearing with me. The third post will follow soon.