21/01/2019

CB1: Functions

This article is part of the CodeBoosting series, where we teach to scientist how to make their code better and shareable.

Intro

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.

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, 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.

Motivation

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.

Mentality

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.

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 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 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 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 allow 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.

Use pure functions

A function is defined pure when it 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 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 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.

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:

  1. Format, pick one and stick with that, the most common looks like:
    1. function_name
    2. function-name
    3. functionName
  2. Naming, if in all the code, when you are calculating a value you used the word calculate, don’t use compute next time.
  3. 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 benefits from using more functions, feel free to get in touch and we can work on it together.

Newsletter

We publish new content each week, subscribe to don't miss any article.

Leave a Reply

Your email address will not be published. Required fields are marked *