Intro

Working in a code base with well-written functions is a pleasurable experience. Everything seems to flow, it 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 to 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.

In this article we will guide you on how to write great functions so that your work will be simpler, nicer to look at, easier to share, and you will be confident in your results.

The first part of the article is about the motivation of writing functions instead of a single big file of operations, then 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.

Motivation

There are several reasons to avoid writing a single long file without any functions.

First, 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 helps 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 readability of your code, indeed if you write good functions it 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 behaves then re-using it into a different project will save you time and effort.

Mentality

In order to write good functions, it 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.

Best Practices

In this part of the article, we are going to show what are some of the best practices to follow when writing functions. This part apply to every programming language, let it be Python or R or C++ or any other.

When writing functions, it is important to have a long-term approach to your code, you will need to ask yourself questions like:

• 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 at 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?

It is important that when we talk to “Another person” that person may be yourself in 6 months by now.

1. Choose a good names

The most important best practice it is definitely the one of picking a good name for your functions and for the input arguments.

A good function name can clearly transmit the intent of the functions to the reader. This allows the reader to have an expectation of the result of the function without the need of running it and without reading the implementation of the function itself.

2. Use pure functions

A function is defined pure when its output depends only on its input, and it is without side effect on the environment where it runs. If your function read a global variable or modify it, then it is not pure and in general it should be avoided.

The reason for this is that it makes it more difficult to assess the correctness of the code.

Pure functions should be preferred since it is trivial to test and to compose them using higher level abstractions.

3. Wrap repeating pattern in a function

A good way to know when you should write a new function is to find a repeating pattern in your code, or even repetition. If you are writing three times the same code, there is a good chance that you should wrap it into a function.

4. Follow the convention in your code

Either implicitly or explicitly, 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: -function_name
  • function-name
  • functionName
• Naming, if in all the code, when you are calculating a value you used the word calculate, don’t use compute next time.
• Input arguments, again, stick with a convention that make sense.

Conclusion

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 benefit from using more functions, feel free to get in touch, and we can work on it together.