Writing Clean Code — Part 3
Making life easier by writing easily readable code
So, this one time I was planning to bake a cake. I was searching online for how to do that. After searching for some time, I found a page, a weird page with a weird recipe to bake a cake. It had a long list of ingredients to bake the cake and 100s of steps to process the ingredients. And the funniest thing was the image of the cake that they attached to the recipe as the end result.
It was overwhelming for me and seemed too much of a work as I was looking for a simple cake recipe. But this one had an immensely long list of ingredients and tedious preparation steps to bake the cake. I lost my hope to bake a cake and got diverted into some other page, as it was not really helpful using that website as a reference.
Baking the cake is a process. Similar to this saving some data is a process, logging in a user is a process. We have multiple such processes in a program. These processes are defined by the functions we write. Similar to the cake recipe, the functions we use in programs are also expected to have a minimum number of ingredients(parameters), a short and simple list of steps(body of the function) and a plausible result(return type).
Irrespective of the situation being somebody who’s going to extend the existing function or utilising it as an API, the function is expected to be minimal, simple and easy to understand. To achieve this we need to write clean functions. Before we move into the discussion about writing clean functions, refer to my previous posts, part 1 and part 2 of clean coding practices.
Clean functions
Functions are nothing but the set of commands to do an operation. We’re already aware of the naming conventions for functions. When talking about clean functions we also need to take care of the method signature, the method body and the return type. Writing and maintaining functions highly depends on all the above factors. Let’s look into each of the factors and how to improve the quality of our functions.
Minimize the number of parameters
The fewer parameters a function has, the easier it is to read and call (and the easier it is to read and understand code where that function is called). The below table represents the ease of understanding functions for the number of parameters used in it and if it is suggested to use such a number of parameters or not.
Let’s look at a little comparison of different method signatures doing the same functionality and investigate which is better to read and understand for that use case.
Consider the functionality to save a user with credentials including email and password. The different ways this can be achieved are:
You could already see how the method signature makes it easy to understand and interpret what a method is doing.
- The first one without any parameters is of course easy to read and digest.
- The second one with one parameter is pretty straightforward, but at times when the naming or arguments used are not defined right, it can be a problem. But still, modern IDEs provide better functionality to see which parameter occurs in the position.
- But when there are two or more parameters, it gets tricky and confuses a little. So beware when going for method declarations with two or more parameters.
But still, there are cases where you can’t avoid three, four or more parameters. You can avoid those situations by utilising proper data structure to pass the parameters, such as a list/array, dictionary or even as objects by creating classes for them, if it has a separate scope of functionality.
Keep Functions Small
Besides the number of parameters, the function body should also be kept small. Because a smaller body means less code to read and understand. But in addition, it also forces you (ideally) to write highly readable code — for example by extracting into other functions which use good naming.
Consider this example:
If you read this snippet, you will probably understand pretty quickly what it’s doing. Because it’s a short, simple snippet.
Nonetheless, it’ll definitely take you a few moments. Now consider this snippet which does the same thing:
Here we have split and extracted each of the individual functionalities into separate functions. Now the login() function is minimal and simple to read and understand.
This is way shorter and way easier to digest, right? Ultimately, that’s what we want! Easy-to-read, easy-to-understand and easy-to-maintain short and focused functions!
Do “ONE” thing
In order to be small, functions should just do one thing. Exactly one thing. This ensures that a function doesn’t do too much. But What is “One” Thing?
It is sometimes difficult to understand how functions do “just ONE thing”. Have a look at the above login() function again. You can argue that the above function does three things: validating the input, finding the user by email and then validating the input password.
Of course, you’re right, it does all these things. But the idea of a function doing "one thing" is linked to another concept: The levels of abstraction that the various operations in a function have. Hold on here, this is another topic to be discussed in the next article.
I think it’s already much to comprehend from a single article about clean functions. Since functions play a major role in programming than anything else, there are more implications in writing clean functions. So we’ll continue looking into writing clean functions in the next article.
The key takeaways from this article would be:
- Write functions with a minimum number of parameters.
- Keep your functions simple to read and understand without writing 100s of lines of code inside a single function. Instead, split into multiple short functions.
Thanks for reading this article! Please post your comments and share them with fellow programmers if you think this is helpful.
(Update) Posted the continuation of this article, jump over and read the article to complete the learning about best practices for writing clean functions.
Join FAUN: Website 💻|Podcast 🎙️|Twitter 🐦|Facebook 👥|Instagram 📷|Facebook Group 🗣️|Linkedin Group 💬| Slack 📱|Cloud Native News 📰|More.
If this post was helpful, please click the clap 👏 button below a few times to show your support for the author 👇
