This article is part of the CodeBoosting series, where we teach to scientist how to make their code better and shareable.
Working in a code base with well written functions is a pleasurable experience. Everything seems to flow, is easy to understand what is happening in the code and adding or removing steps to a particular analysis or simulation is simple and quick.
On the other hand, working with bad functions can be difficult, you are never sure what modify, and even small changes can destroy completely the result of your analysis or simulation.
The problem is so acute that many decide to avoid functions as much as possible, creating a single, long file. This approach is to avoid, especially if you plan to work on the project for longer than a couple of days.
The first part of the article is about the motivation of writing functions instead of a single big file of operations, the we will explain the switch in mentality required to write good functions, finally we will explore some best practices and tricks to write better functions.
There are several reason to avoid writing a single long file without any functions.
First of all, function reduce duplication on the code, so using functions you will write code faster and more correctly. In case of bugs you need to fix only your function in a single part of your code, while if you are duplicating the code you need to apply the same fix in several places, maybe forgetting some location.
Then it help in making the code more testable, indeed, you can test all your function in isolation and make sure that all of them are correct.
Functions help also in the readibility of your code, indeed if you write good functions will be simpler to understand what is happening in the code.
Finally, you can very well re-use in different projects your functions, if the function is well written and you are confident of how it behave then re-using it into a different project will save you time and effort.
In order to write good functions is important to have the correct approach to them.
Functions are a tool to simplify your problem into smaller, simpler parts. Each small part can address in isolation and the original problem can be solved simply putting together all those small parts.
If using functions your code become more complex and difficult to follow, then there is something wrong, probably in the way you structured your functions.
In this part of the
When writing functions
- In 6 months, will I be glad that I wrote this function like this?
- Another person can understand the intent of this function looking only to its name and the input parameters?
- Another person can understand why I wrote the function like this? There was a simpler way to reach the same result?
Is important that when we talk to “Another person” that person may be yourself in 6 months by now.
Choose a good names
The most important best practices
A good function name can clearly transmit the intent of the functions to the reader. This
Use pure functions
A function is defined
The reason for this is because it makes more difficult to assess the correctness of the code.
Wrap repeating pattern in a function
A good way to know when you should write a new function is to find
Follow the convention in your code
Either implicitly or explicity every project has some conventions. As an example you could write your variable like this:
simple_variable or like this
simpleVariable. In the case of functions you should stick to a convention for:
- Format, pick one and stick with that, the most common looks like:
- Naming, if in all the code, when you are calculating a value you used the word
calculate, don’t use
- Input arguments, again, stick with a convention that make sense.
In this short article we explain why writing functions is usually a better idea than a single long file. Then we expose the change in mentality necessary to write good function. Finally we share the most common best practices in the industry.
If you have a piece of code that could benefits from using more functions, feel free to get in touch and we can work on it together.