Aspiring agile software craftsman, clean code, polyglot, in love with different programming paradigm. I am on a never-ending journey towards mastery of software.
This is a Fizz Buzz generator using test driven development.
Problem statement:
The Fizz buzz generator is a simple program, it’s method say generate accepts the numeric input and produces the output string based on the rules and input number.
Rules
The generate method returns the string
FizzBuzz when input parameter is divisible by 3 and 5.
Fizz when input parameter is divisible by 3.
Buzz when input parameter is divisible by 5.
String representation of given number when input parameter neither divisible by 3 or 5.
It is clear that there are four use cases to implement
FizzBuzz As a fizz buzz generator, I should be able to generate a string FizzBuzz for a given input number when the number is divisible by 3 and 5.
Fizz As a fizz buzz generator, I should be able to generate a string Fizz for a given input number when the number is divisible by 3.
Buzz As a fizz buzz generator, I should be able to generate a string Buzz for a given input number when the number is divisible by 5.
Number (converted to string) As a fizz buzz generator, I should be able to generate a string format of input number for a given input number when number is neither divisible by 3 or 5.
After working with the different framework and libraries like Laravel, PHP, ASP.NET MVC, ExpressJS and other technologies, I realized that I should write about naming query variables. Perhaps, variable that holds the query and executes it later (Deferred execution).
Sometimes, when developers of any language or framework choose to write the query that gets data using deferred execution, they don’t include the word “query” in the variable name.
Due to exclusion of word `query` in such a variable name, the maintenance developer presumes that the query will be executed immediately. This assumption leads them to introduce bugs in their code.
Please ensure to include the word `query` in the variable name so that it conveys the reader that it is NOT to be executed immediately.
As always, we have to provide meaningful and intuitive names to query variables. See some of the examples below:
Naming query variable examples
puneCustomersQuery: When I want to fetch the customers in Pune locations.
allPackagesQuery: When I want to fetch all the packages.
evenNumberQuery When I want to fetch even numbers from a given data source.
damagedPackagesQuery: When I want to fetch packages that are marked as damaged.
customersByCityQuery: When I want to fetch customers that are grouped by their city.
customerNameQuery: When I want to fetch customer names from a given data source.
soldOutProductsQuery: When you are fetching the sold-out products.
Imperative programming focuses on describing how a program operates. Take an example of the below function “ isPresent “.
First example: Imperative way, Look implementation of isPresent function.
Of course, it searches a number (search term) in the numbers array and replies with true or false.
If you observe carefully, it focuses on how the number is searched.
It iterates each number one by one in an array of numbers and checks if criteria are fulfilled (HOW part: for/if). Eventually, it tells you if the number is present/not in the array.
I will show you bad and good naming of methods with the help of some code examples. Let’s see some of the typical functions related code smells on a case by case basis.
Smells —
Abbreviations
appointCR(…) : What does CR mean? Appoint code reviewer or class responsible? It was about appointing a class responsible role to a teacher. Hence rename it to appointClassResponsible()
cb = function () { … } // CB?? callback.
handleClk() : This one is supposed to handle Clicked. So, why not rename it to handleClicked, onSaveClicked, onSave or onUpdate?
rand() { return Math.floor(Math.random() * 1000) : rand doesn’t seems to be a method from outside. getRandomNumber() seems okay to me.
Not doing what it says
changePage(url){ this.props.history.push(url); } It was actually nativagating to given url, so, I would rename it to navigateTo(url)?
validationErrors() It was doing student validation. The Name doesn’t tell you anything. I would rename it to validateStudent()?
Use of nouns instead of verbs in method names
jwtAuthentication() – I would rename it to a verb like authenticate()
jwtTokenDecryption() – I would rename it to a verb like decryptToken()
jwtTokenValidation() – I would rename it to a verb like validateToken()
categoryOptions() – I would Rename it to a verb like getCategoryOptions()
Noisy words
getAppointmentInfo()
getAppointmentDetails()
getAppointmentInformation()
Why are you adding noisy/redundant words like Info, Details, Information in front of appointment? In my opinion, getAppointment() gives us information about the appointment. Keep it simple.
Further,
getStudentsList()
getStudentsCollection()
getStudentsArray()
Just getStudents() make sense to me. You don’t need to tell your audience about how’s your implementation under the hood.
Not symmetric
turnOn()/disable()
openConnection()/shutConnection()
increaseVolume()/turndownVolume()
If you are adding symmetric methods, then make sure they feel symmetric one.
turnOn()/turnOff()
openConnection()/closeConnection()
readFile()/writeFile()
increaseVolume()/decreaseVolume()
Not having descriptive/searchable names
booleanValue(value)?? Oh! After browsing the code, I realized that it was converting the string value to boolean. I would rename it to toBoolean(value)
deactivate() :It was deactivating the membership. I would rename it to deactivateMembership()
invoke(): It was invoking a controller’s action. I would rename it to invokeAction().
disable(): Disable what? Authorization? I would rename it to disableAuthorization().
handle(): Handling what? Handling subscription? I would rename it to handleSubscription().
One word per concept
fetchActiveStudents()
retrieveActiveStudents()
getActiveStudents()
Why are you using different words (fetch, retrieve, get) for the same concept? Just choose one word per concept and use it throughout your project.
getActiveStudents()
getPackages()
getAppointments()
Side effects
ValidateToken() should NOT create a token. I would take `create token` logic out of the method. It’s a side effect.
getValue(key, callbackForCreate) should not create value for a given key. Sometimes, people try to get a value from the cache for a given key. If the value is absent then they try to create value inside the cache using a given callback function. I would separate these concerns into different functions. Read more about command query separation.
createUser() — This method was doing multiple things. It was validating user inputs, creating a user, sending registration email using asynchronous operation. This method seems like registerUser() and it should outsource the responsibilities to validateUser(), createUser() that stores a record and sendEmailAsync() method that conveys that email would be sent later.
If you are not going to refactor it into three new methods due to the deadline, then at least rename it to registerUserAndSendEmail()
Look for anti-patterns:`And`, `Or`, `If`.
createUserAndSignToken() createOrUpdateUser() If a method contains keywords like And, Or, If in its name, it’s an indication that the method is doing more than one thing, which is a violation of the Single Responsibility Principle.
Command and query in one function
fetchAndSaveCategoryDetails() method is not just doing more than one thing, but also executing command and query in one function. The best thing is to simply separate command and query. Create separate functions. fetchCategory() and saveCategory().
The guidelines for naming methods:
FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY… Clean code by Uncle Bob.
The function should be cohesive. The function should say what you mean. The consumer of the function should not browse your function to see what it is doing.
Separate command and query: Create a separate function for command and query. Here, command means to save, update, delete the records and query means all get or list methods like getStudent(id), getActiveStudents() etc.
Explore open source projects for your technologies and explore how names are given. I explored many JavaScript libraries, Lavavel PHP source code, .NET source code: https://referencesource.microsoft.com/
Let me walk you through some of the bad and good examples first and show you the useful notes at the end of the post.
Uglier ways of naming modules or classes
myClass: Lazy ways of naming classes. Does it answer it’s purpose clearly?
Anything that is suffixed by general words like Manager, Helpers, Info, Data, Details, Utility.
CSVHelper: Is it formatting, serializing, converting data into CSV? Are you sure it is answering the questions?
XMLUtility: Same as above.
JSONManager
AppointmentEntity: Is this a Transfer object?
AppointmentBO BO: Business object; doesn’t your programming language have namespace or package?
Common, Utility, Helpers: Wow! Put all the garbage here. The magnet class that attracts all lazy developers. They do their sins in this class.
Processor
StudentData, StudentDetails, StudentInfo, StudentInformation: What will happen if I simply give a name:`Student`? It is also a piece of student information, isn’t it?
QC: Avoid abbreviations. We are here to solve the problem and make collaboration easy within the team. Avoid abbreviations.
BatchJob: This was a base class for all jobs that can be queued in a batch. Does that convey anything related to base class?
JWTAuthentication: Are you yelling at others about implementation?
Let’s go through some of the good examples of naming classes.
Cleaner ways of naming classes:
Appointment: You have ways to locate your classes using namespace so instead of appending general words like Entity, or BO, or AppointmentEntity, use namespaces wisely.
DateFormatter: It formats the date based on the given format. Makes more sense than DateHelper or DateUtility, right?
MeetupSerializer: It serializes the meetup object into a string representation. Intuitive?
DocumentFileStorage: It tells you about its central purpose like Reading/Writing a document to a file system.
UserRepository: It tells you that it’s a repository pattern for User. If your language supports generics, then Repository<User> could be a better solution.
MoneyFormatter: It formats the money.
ColorCodeProvider.getColorCode(value). It gives you a color code for a given value.
QualityCheck is better than QC
StudentProgramSearch, The search entity that contains fields related to a student and his education program.
StudentValidator.
Logger
ControllerFactory: It creates controllers.
Sanitizer
UpdateCommandSanitizer: It should ignore some of the fields from user input like CreatedAt and UpdatedAt fields and prepare update command for updating other fields.
PersonDataSanitizer: It clears some of the person fields like phone, email, address and sends data for remaining fields.
Giving a name to a class is art. To learn that art, I would recommend you to read, understand and apply: Abstraction, Cohesion, and Single responsibility principle. You will also need to understand the conventions of the framework you are using e.g. MVC as well as learn design patterns.
Don’t forget to ask these questions while naming the class.
Does your class name describe its central purpose? and doing those things only? Example: Abstract data types like Stack, Queue, etc.
Does your class answer your questions like what it is doing? Rather than how is it doing?
Name your classes using a noun, according to their domain and architectural meaning.
What do you want to achieve? Ask repeated questions. For e.g. Formatting? what kind of formatting? Money? Then the name should be MoneyFormatter…. Similarly, Converting document into JSON? OK, but why are you doing it? Do you want to serialize document? Then it should be named DocumentSerializer rather than JsonConverter.
Can a class be treated as a black box? Visibility of the members? Use class diagrams for clarity.
Does class make assumptions about the consumer of that class?
Does your class name feel more generic or specific?
Choosing a name has a huge impact on the readability of the code.
In this post, I will walk you through some of the bad and good examples which might convince you why naming matters.
Project directories:
Three projects, guess which one is admin site, native mobile app, and restful API?
Can you guess which project serves as an admin website, mobile app, and server-side API’s? The developer not only failed to give attention to naming but also masked his intent with some other words. Confusing?
The sentence:
P and Q went to R. They had a good dinner at S followed by T and then they came back to U.
Could you read the above sentence and understand it’s clear intent. For me, it’s difficult to understand due to the usage of abbreviations. It will lead me to different assumptions.
Code snippet:
Random code snippet
I am sure you have figured out what the code is doing. However, it was not that easy to figure out this code snippet.
Now think about a project that contains more than 1000+ classes, modules, methods, files, and many more.
The complexity and frustration will be increased in the same magnitude if developers don’t give attention while naming those.
Don’t you think it will be painful for the maintenance developer as well as your future-self to visit and understand the intent behind the code?
Real-life analogy
Everything in this world has meaningful names. It helps our brain to understand, remember and figure out the things at ease. It means less mental mapping.
When you visit hypermarket, you could easily figure out groceries, fruits, cosmetics and so on.
You could easily fetch handwash, facewash, aftershave, sanitizer, liquid sanitizer, moisturizer, cold-drinks, cookies, water bottle and so on. Thanks to proper naming to the categories, items and so on.Naming matters!
Let’s revisit the above examples with careful naming.
Project directories:
Uglier way:
Three projects, guess which one is admin site, native mobile app, and restful API?
Better way:
See projects after renaming, are you able to figure out which one is admin site, mobile app, and API at ease?
The sentence:
Uglier way:
P and Q went to R. They had a good dinner at S followed by T and then they came back to U.
Better way:
Tom and Jerry went to a Mall. They had a good dinner at a restaurant followed by a movie and then they came back to their Home.
Do you realize the power of effective naming?
Code snippet:
Uglier way:
Random code snippet
Better way:
Find the Volume and Surface Area of Cuboids
Just looking at code snippet, it is crystal clear that code is working on height, length, and breadth to compute surface area and volume.
Now with proper naming to the variables, A small code snippet with careful variable naming makes developers life easy.
Imagine what will happen to readability, understandability, and maintainability if you show the same dedication while naming everything in the project.
We as a programmer try to solve the customer requirement or problem by creating various projects.
These projects may have directories, assemblies, namespaces, packages, files, classes, modules, properties, fields, events, method arguments, method parameters, UI elements, UI attributes, UI styles, validators, services, translation files, translation keys, command-line utilities and many more.
All of these things should have a meaningful name so that they convey their intent. You should be able to figure out what they are doing by just looking at their name.
Perhaps they should answer all the big questions that you or future maintenance developers would have.
Naming matters! Please give attention to naming everything in the programming!
What do you understand after reading the above number?
It is just raw data. The interpretation is left to the reader of the data.
However, the reader may not get the intent behind it.
It could be a zip code of a city.
It could be a birthday in DDMMYY format.
It could be a telephone number without the area code.
It could represent N number of things.
Do you agree with me that using just raw data does not convey its intent?
Similarly, a magic number in code is like raw data which does not convey its intent to the reader of the code.
A magic number is a numeric value that is used in the code. This value has unexplained meaning and hampers readability of the code.
Above code reads like John failed to upload his profile picture because the size of the profile picture was more than 10000000.
Here I did not understand the meaning of magic number 10000000.
Whether it is a size in Bits, Byte, KB, MB, GB?
Well, let’s introduce the named constant and see what happens.
Now, the code reads more like John failed to upload his profile picture because the size of the profile picture was more than maximum allowed file size i.e. 10000000 bytes.
As soon as you give metadata about the data i.e. relevant data it becomes information to the reader. The reader can work with it easily as the intent is clear.
Another example:
Bad way
When the given day is 0 or 6, Magic number! then put ‘-’ in cell content.
Better way
When the given day is Sunday or Saturday then put ‘-’ in cell content.
Thus, named constants could be used to provide data about raw data so that reader of your code could easily figure out the intent.
Conditionals play a vital role in code for performing business decisions. These conditionals should be easy to read.
If conditionals are complex then it might hamper readability. You would end up introducing more bugs if failed to understand its intent. Every time you visit this code, you will need to debug it to understand the intent.
Complex conditionals:
Complex conditional determines something to perform business rules
Look at above conditionals in if clause. It is clear that it is performing too many checks related to the package of the items. Please note that this package was ordered from an online e-commerce site and then performs important business decisions.
It will be difficult for the maintenance programmer to figure out each condition and know what question it tries to answer.
Let’s make the maintenance programmer’s life a little easy by writing readable code using encapsulate conditionals that have intuitive names and give the answer in yes/no format.
Better way:
Complex conditionals are extracted to a method. An intuitive name is given that tells what it is doing. The complex conditional block would be simplified like this. It reads like perform business decisions if a package is eligible for a return.
Another complex conditional
Too many questions here.
Preferred way:
A simplified version with clear intent: can view editor?
