Clean code: Naming to achieve clean code.

April 28th, 2023

Author: Justin Khanh – UPP Delivery

clean-code-p2-thumbnail

Selecting appropriate and clear names for variables, properties, functions, methods, and classes is a fundamental aspect of creating clean code. It is essential because if inadequate names are chosen, the other concepts in this series will not be of much help.

1. Be Descriptive The main goal of names is to convey the nature of the data stored in a variable or property, the purpose of a function or method, or the type of object that will be generated when creating a class instance. If you keep this objective in mind, selecting suitable names should be a straightforward process. However, determining the optimal name for a particular variable, property, or function may require some practice and multiple attempts. This is standard in the process of writing clean code, which involves iterating and refining the code over time to improve its quality.

2. Naming Rules 2.1 Variables & Properties Variables and properties serve as containers for various types of data, such as numbers, text, booleans, objects, lists, arrays, and maps. As such, the name of a variable or property should convey the type of data it stores. It is generally recommended to use a noun as the name of a variable or property, such as user, product, customer, database, or transaction. However, a short phrase with an adjective can be used for boolean values, such as isValid, didAuthenticate, isLoggedIn, or emailExists. Whenever possible, it is advisable to use more specific names, such as customer instead of user, if the code operates on customer-specific data. This improves code readability and understanding.

2.2 Functions & Methods Functions and methods are executed to perform tasks and operations. Thus, their names should indicate the action they perform. It is recommended to use a verb as the name of the function or method, such as login(), createUser(), database.insert(), log(), etc.

In cases where functions and methods produce values, especially boolean values, short phrases with adjectives can be used, such as isValid(...), isEmail(...), isEmpty(...), etc.

Avoid using names like email(), user() as they resemble property names. Instead, use more descriptive names like getEmail().

Like with variables and properties, using more specific names is preferable. For instance, instead of using create() as the name of a function, it is better to use createUser() to be more specific about its purpose.

2.3 Classes Classes are responsible for creating objects, except in cases where they are static. It is important to use a class name that describes the type of object it creates. Even in the case of a static class that cannot be instantiated, it is still used as a container for data and/or functionality, and therefore should be described as such. Good class names, much like good variable and property names, should be nouns. Examples of good class names include User, Product, RootAdministrator, Transaction, and Payment.

3. Avoid Generic Names It is generally advisable to steer clear of using generic names such as handle(), process(), data, and item, unless there are compelling reasons to do so. In most cases, it is better to use more descriptive and specific names. For example, instead of using handle(), you could use handleRequest(), or instead of using item, you could use product.

4. Be Consistent Consistency is a crucial aspect of using appropriate names in programming. If you utilize "fetchUsers()" in one segment of your code, it's vital to use "fetchProducts()" instead of "getProducts()" in another part of the same code. While it doesn't matter if you choose "fetch...()", "get...()", "retrieve...()" or any other term, it's essential to be consistent!

Tags
Frontend Development
Mobile App Development
share icon
Share