Clean Code — Naming
What is Clean Code?
Clean code is code that is easy to understand and easy to change.
Few code clean guidelines would be:
- Should be readable and meaningful
- Should avoid unintuitive names, complex nesting and big code blocks
- Should be concise and “to the point”
- Should reduce cognitive load
- Should follow common best practices and patterns
- Should be fun to write and to maintain.
A clean code takes time, effort, attention and care, values which are not taken into consideration by most of the business. The clean code falls into the Quality criteria of the Quality Triangle known as Project Management Triangle.
Writing a clean code and focus on quality indeed takes more time but it will produce a more sustainable product for the long term.
Key points of Clean Code
Clean code is all about:
Naming — How to use proper names
- Variables
- Functions
- Classes
Structure and Comments
Functions
- Length
- Parameters
Conditionals and Error Handling
- Deep Nesting
- Missing Error Handling
Classes and Data Structures
- Missing Distinction
- Bloated Classes
All of them takes us to:
Solutions
- Rules & Concepts
- Patterns & Principles
- Test-Driven Development
In this article I’ll talk about the first topic when it comes in writing clean code and that’s it naming, how should we name things when writing code.
Naming
Naming things correctly like variables, properties, functions, methods, classes and in an understandable way is an important part of writing clean code.
Be Descriptive
Names have one simple purpose and they should describe what’s stored in a variable or property or what a function or method does. Or what kind of object will be created when instantiating a class.
Using good names should actually be straightforward, but coming with the best name for a given variable/property/function will still require practice and often multiple iterations. But it’s normal, clean code is written by iterating and improving code over time.
Naming Rules
Variables & Properties
Variables and properties hold data — numbers, text (strings), boolean values, objects, lists, arrays, maps etc.
Hence the name should imply which kind of data is being stored.
Therefore, variables and properties should typically receive a noun as a name.
For example: user, product, customer, database, transaction
Alternatively, you could also use a short phrase with an adjective — typically for storing boolean values.
For example: isValid, didAuthenticate, isLoggedIn, emailExists
Typically, if you can be more specific, you should be more specific.
For example, prefer customer over user if the code at hand is doing customer-specific operations with that data. This makes your code easier to read and understand.
Functions and Methods
Functions and methods can be called to then execute some code. That means that they
perform tasks and operations.
Therefore, functions and methods should typically receive a verb as a name.
For example: login(), createUser(), database.insert(), log()
Alternatively, functions and methods can also be used to primarily produce values — then, especially when producing booleans, you could also go for short phrases with adjectives.
For example: isValid(…), isEmail(…), isEmpty(…)
You should try to avoid names like email(), user() . These names sound like properties. Prefer getEmail() instead.
As with variables and properties, if you can be more specific, it typically makes sense to use such more specific names.
For example: createUser() instead of just create().
Classes
Classes are used to create objects (unless it’s a static class).
Hence the class name should describe the kind of object it will create. Even if it’s a static class (i.e. it won’t be instantiated), you will still use it as some kind of container for various pieces of data and/ or functionality — so you should then describe that container.
Good class names — just like good variable and property names — are therefore nouns.
For example: User, Product, RootAdministrator, Transaction, Payment
Avoid Generic Names
In most situations, you should avoid generic names like handle(), process(), data, item.
There are situations where it makes sense but typically, you should either make these names more specific, like processTransaction() or go for a different king of name, like product instead of item.
Be Consistent
An important part of using proper name is consistency. If you used fetchUsers() in one part of your code, you should also use fetchProducts() and not getProducts().
Generally, it doesn’t matter if you prefer fetch, get, retrieve or any other term, just be consistent.
Hope this will be helpful in your journey as a Java programmer and keep up the good code!
And don’t forget to check my new blog JavaCodeBox.
