Writing Clean Code. Proper Naming for variables, methods and classes(Part 1).

Proper Naming is Hard and it takes years of development to really understand the power and importance of expressing Real Intent.

Issues with Naming:

• Misleading names that mask the real intent.
• Not honoring the Single Responsibility Principle.
• Not realizing that it worths spending more time for finding the correct name.
• Names have a great impact on the readability of the code.
• Correct Naming is really hard.

Naming Rules:

1. Stick to the Format

• Variables: verbs and nouns, but is in favor of using only nouns.
• Methods: action + noun.
• Classes: only nouns, not verbs.
  You are creating an instance of that thing.
  Bad: ThrowNotFoundError.
  Good: NotFoundError.

2. Avoid generic names:

• Variables:
  Bad: data, result.
  Good: product, user.
• Methods:
  Bad: get, create.
  Good: getAvailableUsers, getProducts, createTicket.
• Classes:
  Bad: MyUtility, Common, etc.
  Good: User, Ticket, Product.

3. Use a Consistent Word per Concept:

• Variables:
  Bad: userAddress, userLocation; using all of them.
  Good: using only one of them.
• Methods:
  Bad: fetchUser, getUser and retrieveUser; using all of them.
  Good: using only one of them.
  Bad: add method in UserService adds an element at the end of an array, add method in ProductService concatenates 2 arrays.
  Good: renaming them: push, merge.
• Classes:
  Bad: ProductLocation, ProductAddress; using all of them.
  Good: using only one of them.

4. Avoid adding noise:

• Variables:
  Bad: userInstance, isValidBoolean, ageNumber.
  Good: user, isValid, age.
• Methods:
  Bad: validateUserEmailFormatMethod, getAgeNumber.
  Good: validateEmail, getAge.
• Classes:
  Bad: UserClass, AppUserClass.
  Good: User.

5. Avoid side effect:

• Methods:
  Bad: validateEmail will validate the email but also save the email.
  Bad: validateEmail will validate the email but also logout the user if the email is not valid.
  Good: validateEmail should only validate the email.
• Classes:
  Bad: UserRepository will send Emails.
  Bad: UserRepository will create Products.
  Good: UserRepository will do only the CRUD operations on the DB.
  Just the name UserRepository should prevent others from adding other functionality that doesn’t belong there.

6. Granular and specific as possible. The Name marks the intent.
Poor naming doesn’t mark the real intent.
There is a thin line between being as specific as possible and avoiding noise, but the former one is worse, so be specific as possible even if you add noise.

• Variables:
  Bad: updatedAt, friends.
  Good: recordLastUpdatedAt, friendsOfCurrentUser.
• Methods:
  Bad: checkUser; doesn’t really marks the intent.
  Good: validateEmail marks the real intent.
  Bad: getUpdatedAt.
  Good: getRecordLastUpdatedAt.

7. Avoid abbreviations.

• Variables:
  Bad: cUser.
  Good: currentUser.
• Methods:
  Bad: getU.
  Good: getUser.
  Bad: authUser.
  Is this the authenticatedUser variable?
  Is this the authorizedUser variable?
  Is this the authorizeUser method?
  Is this the authenticateUser method?
  Good: authenticateUser.
• Classes:
  Bad: DCurrency, CCard.
  Good: DollarCurrency, CreditCard.
  Bad: CurrencyI.
  Is this an Interface? Is this a Class implementation for Israeli/Indonesian/Iceland Currency? Is this Currency Index?
  Bad: UserAuth.
  Is this an UserAuthorization? Is this an UserAuthentication?
  Good: UserAuthentication.

8. Avoid numbers

9. if/and/or/etc.. are signs that the single responsibility principle is not respected. It is a sign that a split should occur.

• Methods:
  Bad: validateEmailAndName.
  Good: validateEmail, validateName.
• Classes:
  Bad: UserWithEmailValidator.
  Good: User, EmailValidator.

10. Be Positive

• Variables
  Bad: isDisabled.
  Good: isEnabled.
• Methods:
  Bad: getNonActiveUsers
  Good: getActiveUsers

11. How to find the Right Name?

• Methods:
  Verbalize in your own mind what that method does.
  Find similar method names in the existing code and add a word that will differentiate it from them.
  Invest time, it worths.
• Classes:
  Verbalize in your own mind what the Instance of the Class is.
  Find similar class names in the existing code and add a word that will differentiate it from them.
  Invest time, it worths.

12. Boolean Variables Format:
Bad: valid, validate, open, deleted.
Good: isValid, shouldValidate, isOpen, isDeleted

Published at https://flawless-bits.com/blog/clean-code-proper-naming
Have a Great Day!