4 min to read
Python - Writing functions - best practices
This article is a part of the Python - 101 series, you can access the full version of the series here:
-
Coding 101
-
Writing functions in Python
- Basic
- Scope of variables
- More on arguments and lambda functions
- Best practices (you are here!)
-
Control flows in Python
-
Errors and exceptions
-
Classes
Welcome to the sixth article of the Python - Coding 101 series, after reading this article, you’ll learn:
- How to make your code easier to read and debug
- Rules in function writing
We have covered all we need to know about functions in Python. To make your code more efficient, here are some tips
- 1. Docstring & Comments
- 2. Naming your functions
- 3. Organizing your functions
- 4. Single responsibility principle
- 5. Idempotency and Functional Purity
1. Docstring & Comments
1.1. Docstring
Docstring can be understood as documentation in Python. It can be used in the class, module, function, or method definition. Docstrings help you understand the capabilities of a module or a function.
To write a docstring in Python function, you need to wrap it inside 3 double quotes """...""". For example:
def add_one(x):
""" add one to the argument passed """
x = x + 1
return x
Docstrings are accessible from the doc attribute (__doc__) for any of the Python objects and also with the built-in help() function.
print(add_one.__doc__)
help(add_one)
1.2. Comments
Comments are very similar to Docstrings. But comments are mainly used to explain non-obvious portions of the code and can be useful for comments on fixing bugs and tasks that are needed to be done.
To write a comment in Python function, you start your line with a #. For example:
def add_one(x):
# add 1 to the argument passed
x = x + 1
return x
Note that comments can not be accessed with the built-in __doc__ attribute and help function.
2. Naming your functions
In coding in general, there are some rules for naming a variable, the main purpose of it is not only to ensure that Python does not return any error, but it also help make your code more robust. The rules are as following:
- They must start with a letter or an underscore:
_. - They should be lowercase.
- They can have numbers.
- They can be any length (within reason), but keep them short.
- They can’t be the same as a Python keyword. They can have the same name as an existing function (including a built-in), but avoid this for now.
3. Organizing your functions
If it’s a simple project with only a few functions you may want to define them at the beginning of your Python module. If your project size is a bit bigger you may want to put them into their own module so that they can be imported into your code and used wherever.
You may also want to create methods for classes. These topics are beyond the scope of this article, but you can follow this series to learn more.
4. Single responsibility principle
The Single Responsibility Principle means that one function has only one and only one purpose.
By doing this, a function can easily be reused. It also makes it easier to debug your program. Remember the last exercise from the last article, try writing functions that follow single responsibility principle.
5. Idempotency and Functional Purity
An idempotent function always returns the same value given the same set of arguments, regardless of how many times it is called. The following add_three(number) function is idempotent:
def add_three(number):
"""Return *number* + 3."""
return number + 3
No matter how many times one calls add_three(7), the answer will always be 10. Here’s a different take on the function that is not idempotent:
number = 1
def add_three():
global number
number = number + 3
Comments