- Design first: You understand requirement first via analysis, create use cases for it. Thus, the focus is on the requirement before writing the code.
- Good enough code for now: You write sufficient code against use cases that fulfills the user requirements. You don’t write extra lines of unnecessary code.
- Avoid rework: Due to design first approach, most of the doubts are cleared before writing code hence rework is avoided.
- Developer confidence: Continous delivery of requirement in small cycles gives developer a confidence.
- Regression catching.
- Safe Refactoring: Once the code is covered by multiple tests, a developer can safely improve code structure with confidence and can focus on simple and elegant design.
- A shared understanding of the business: Tests are the live documentation that is the communication channel between you and your future version or other developers that talks about business rules.
- Clean code reminder: IMO, TDD always reminds you to make your code better than you found it. Of course, after covering your code with test, make it better.
Author: Dattatraya Kale
Aspiring agile software craftsman, clean code, polyglot, in love with different programming paradigm. I am on a never-ending journey towards mastery of software.
Rest parameter under the hood…
You know the rest parameter (usually prefixed with ...) allows functions or methods to accept indefinite numbers of parameters.
This parameter is actually gathering the values from arguments and creates an array of values from it.
How? Let’s see with code using ES6 rest parameter and it’s corresponding transpiled version.
Simple snippet with rest parameter
Obviously, line 2 will print an array
[ 'Monday', 'Tuesday', 'Wednesday' ]
You wonder, How it’s an array? Let’s inspect it via
Below code is transpiled using BABEL.
Transpiled version:
Under the hood, the rest parameters are actually derived from arguments object of called function, `print`. Please notice carefully variable days on line# 5.
It’s value is set to an array whose length is equal to number of arguments passed.
Later, elements from arguments are copied to variable days (element by element from line# 8 to 10).
Another Example
In the second code snippet, please note there is a parameter multiplier apart from rest parameter ...numbers. Hence, copying will not begin from first element instead it started from second element till last one.
See transpiled version for more details.
Transpiled version
const does not mean value it holds is immutable
I see many JavaScript developers have started replacing var with const just because some linter forces them to do so.
const in JavaScript is not only blocked scope but also const variable cannot be reassigned with new content.
It creates readonly reference. It means you cannot reassign value to the const variable. It does not guarantees immutability of the content that it holds.
const person = { name: 'John Doe', age: 33};
person = { name: 'John'}
// Above line will throw Uncaught TypeError:
// Assignment to constant variable.
// However, you can change the content of object
// that is referenced by person variable.
person.age = 40;
So, If you really want to mark your object as immutable then use some other API’s like `Object.freeze`.
There are specific use cases about const variable. Make sure you are intentionally marking some variable as const and not because some linter has that rule.
Fizz-Buzz generator using test driven development
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
FizzBuzzwhen input parameter is divisible by 3 and 5.Fizzwhen input parameter is divisible by 3.Buzzwhen input parameter is divisible by 5.String representation of given numberwhen 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 FizzBuzzfor 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 Fizzfor 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 Buzzfor 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 whennumber is neither divisible by 3 or 5.
Visit the github repository fizz-buzz-generator for TDD implementation.
Don’t forget to go through commit by commit to witness the test driven development journey.
Naming query variables
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.
Be declarative wherever possible
Imperative programming focuses on describing how a program operates. Take an example of the below function “ isPresent “.
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.
Declarative programming, on the other hand, expresses the logic of a computation without describing its control flow.
Let’s look at the declarative way of searching a number in an array.
Any function from LINQ. In the above code, the method Any (present on array data type), is an extension method provided by LINQ.
It determines whether any element of a sequence contains a given number. It does not tell you how it is searched. That part is hidden behind API: Any.
The benefit of a declarative approach over the imperative approach is improved readability of code.
Another example:
This function “ containsAllMen “ tells you how searching is implemented and control flow like if clause determine the condition.
Now see the declarative way, it is using lodash’s every to determine the condition.
every function from lodash. This technique is language agnostic.
You search libraries that do such work for you instead of implementing it by yourself.
Naming functions or methods
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 tovalidateStudent ()?
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/
Naming Modules or Classes
The thinking in this post is applicable to the class as well as modules. However, in this post, I’ll use the word class.
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?
Return as early as possible
Do you know how to check if the given year is a leap year or not?
Let us go through a simple leap year code snippet.
The above code snippets read like:
If a given year is divisible by 4, 100, and 400 then given number is a leap year.
If a given year is divisible by 4 and 100 but it is not divisible by 400 then it is NOT a leap year.
If a given year is divisible by 4, but it is NOT divisible by 100 then it is a leap year.
Otherwise given number is NOT a leap year.
Did you realize that readability is poor when you use deeply nested conditionals?
Even a simple program becomes difficult to understand.
This is called Arrow anti-pattern because too many nested if represent an arrow-like shape.)
Readability could be achieved by returning as early as possible.
Let’s see via example.
Don’t you think the second one is easier to understand?
It reads like
If a given year is divisible by 400 then it’s a leap year.
Otherwise if divisible by 100 then it’s NOT a leap year.
Otherwise if divisible by 4 then it’s a leap year.
Oherwise it’s NOT a leap year.
Naming Matters
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:
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:
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
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:
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:
Better way:
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.