Avoid complex conditionals using the ternary operator

?: is a ternary operator introduced to write elegant if-else clause.

It is a concise way of writing simple conditionals. However, those should be easily understandable by any human. It should not be used to write deeply nested complex conditionals that hamper the readability.


When to use?

When you have very simple if-else that could be covered in one line and returns value.


Example:

Display text as “Weekend” if it’s a Sunday otherwise “Working day”

Another one:

Determine the restaurant to visit depending upon cash in your wallet.

When NOT to use?

As said earlier, they are used to simplify the conditional so that they add value and make code simple and elegant.

However, that does not mean you should blindly rewrite ALL if-else clause with the ternary operator. Please avoid them when expression becomes complex and difficult to understand.


Bad Example

The implementation of the fizz buzz generator.



const output = number % 3 === 0 && number % 5 === 0 ? "FizzBuzz"
 : number % 3 === 0 ? "Fizz" 
 : number % 5  === 0 ? "Buzz" 
 : number;

In my career, I have seen people writing deeply nested clauses using the ternary operator. I kept the above example to convey my thoughts.

The above snippet adds unnecessary mental mapping to remember and process each conditional and symbols ?: ?: ?: more like a machine.

Please don’t be a human code compressor.

Better alternative

Conventional if-else over ternary when a condition becomes complex.

Day by day, high-level languages are introducing more features so that developers could write more human-readable expressive code. We should keep this point in our mind and avoid a few things like writing deeply nested complex ternary conditionals. Instead, go for conventional control flow statements like if-else or if-return-early.

Thoughts mentioned in this post are based on my personal experience. It is just a guideline. IMO, we should be compassionate about our co-worker while writing the code and should avoid clever-complex clauses using ternary operators and rather should focus on elegance.

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.

Naming functions or methods

Photo by Markus Spiske on Unsplash

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/

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.

Photo by rawpixel on Unsplash

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?
Photo by Hutomo Abrianto on Unsplash

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.

 

Tells you whether the given year is a leap year or not.

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.

Returning as early as possible

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.

Dattatray Kale | Being software craftsman
I am an application developer based in Pune, India. I am willing to wait for the right opportunity – Datta CV PRACTICES…blog.beingcraftsman.com

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:

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.

Photo by Bernard Hermant on Unsplash

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!


Dattatray Kale | Being software craftsman
I am an application developer based in Pune, India. I am willing to wait for the right opportunity – Datta CV PRACTICES…blog.beingcraftsman.com

Replace magic number with named constants

120308

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.

Hence, Replace magic number with named constants.

Encapsulate conditionals

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?

Dattatray Kale | Being software craftsman
I am an application developer based in Pune, India. I am willing to wait for the right opportunity – Datta CV PRACTICES…blog.beingcraftsman.com

Don’t be anti-negative

The negative conditionals in code blocks are most of the time difficult to read and understand.

It becomes worse when you make the conditionals anti-negative.

Before

Anti-negative conditionals

Try to read above code snippets and try to understand it. Please note the highlighted parts. Does that code reads like

  • When inverse of a package is not damaged then report an error: “Package is damaged”.
  • When inverse of a package is not empty then report another error:
    “Package is empty”

Ouch! Unreadable? Complex? Painful, isn’t it? Let’s revisit the same condition with positive conditionals.

After

Positive conditionals

Another example:

Before:

Set hours logged when it is not NonWorkingDay. What?

Above snippet is showing hours worked for the day if it’s not non-working day!

After

Set hours logged when it was working day.

Now, this reads like simple statement. Show hours worked for working day.


Extract Method

Extract method is the most frequently used refactoring technique. It reorganizes the code for better reuse and readability.

Ah! alright. Let’s proceed.

Use the extract method in following cases —

When your class contains a long method.

A long method does more than one thing and it is not considered as cohesive. The method more than 10 lines could be considered the as long method.

See this example of a long method, It is doing more than one thing.

Setting up GST rates, item/category mapping, accepting user inputs, calculation and so on. 

A long method is considered a code smell. 

Now see the refactored version of the above long method.

It is divided into small, cohesive, fine-grained methods which are doing one and only one thing.


When you favor a comment to express the intent of the code.

Before

 ...
// Parse input and convert it into Document
var xDocument = XDocument.Parse(input);
var document = new Document
{
   Title = xDocument.Root.Element("title").Value,
   Text = xDocument.Root.Element("text").Value
};
...

Here let’s get rid of comment [Parse input and convert it into Document]. 

After

...
var doc = ParseInput(input);
var serializedDoc = JsonConvert.SerializeObject(doc);
...
private Document ParseInput(string input)
{
    var xDocument = XDocument.Parse(input);
    var document = new Document
    {
        Title = xDocument.Root.Element("title").Value,
        Text = xDocument.Root.Element("text").Value
    };
    return document;
}

When the extract method helps you to improve readability.

Do you know that people extract method for a single line too? Because it adds to the readability of the code. Sometimes a statement may be difficult to interpret. In that case, you could use the extract method to convey intent instead of taking the aid of comment.


When there is a code duplication or copy-paste.

Consider below example, it is formatting date and code is duplicated. Perhaps, lines are copied and pasted.

Before

    var formattedStartDate = startDate.ToString("dd MMMM yyyy");
    var formattedEndDate   = endDate.ToString("dd MMMM yyyy");

As soon as you see copy and paste of lines of code then go for an extract method refactoring even if it is a small portion of code.

After

    var formattedStartDate = FormatDate(startDate);
    var formattedEndDate  = FormatDate(endDate);

public string FormatDate(DateTime date)
{
   return date.ToString("dd MMMM yyyy");
}

The advantage

  • Code becomes more readable.
  • Fine-grained methods make code easier to understand.
  • You can easily plug-in and plug out the implementation for some routines.
  • When your method becomes cohesive, you can easily spot the bugs in the code.
  • Your calling method reads more like a sentence.

Points to Ponder —

  • Remember, keep the method short, well-named, and cohesive to get more benefits out of it.
  • Your calling method should read more like sentences.
  • When extracting a method, a developer should think about the cohesiveness of the class. should ask a question to oneself: Does the extracted method really belong to this class? If Not, then move it to the appropriate class that should perform that operation.
  • Small methods really work only when you have good names.
  • Don’t just extract method if you can’t give the meaningful name.

Extract method only if you can give an intuitive name.