I don't know if my friends are so confused. When we look back at some of the code we wrote 6 months ago, we are often confused.
There are many ways in Python to help us understand the inner workings of our code, and good programming habits can make our work more efficient!
For example, we might end up with code that looks a lot like the image below. Not the worst, but, we need to extend some things like:
-
What do the f and d in the load_las_file function stand for? -
Why do we check the result in the clay function? -
What types do these functions need? Floats? DataFrames?
In this article, we'll focus on five basic tips on how to improve the readability of your application/script through documentation, prompting for input, and proper variable names.
1. Comments
The first thing we can do with our code is to add certain comments to our code, but not overdo it. Comments should tell you why the code works or why something is done a certain way, not how it works.
Comments in Python are usually done using the pound sign (#) and can span a single or multiple lines.
# Comment using the hashtag
# Another comment using the hashtag
For multi-line comments, we can also use three double quotes.
"""
This is an example of
a multi-line comment
"""
In the example below, some comments have been added to the code to explain the workflow and reasoning behind certain lines of code
2. Explicit Typing
The Python language is dynamically typed, which means that variable types are only checked at runtime. Also, variables can change type during code execution.
Static typing, on the other hand, involves explicitly stating what type the variable is and cannot change during code execution.
In 2014, PEP 484 introduced the concept of type hints, and later in Python 3.5, these allow us to explicitly state what type a variable should be.
By adding type hints, you can significantly improve the readability of your code. In the following example, we can easily get the following information:
-
The function requires two parameters -
The filename parameter should be of type string -
The start_depth parameter should be of type float, the default value is None -
The function will return a pandas DataFrame object
We can immediately tell exactly what the function needs and what it will return based on the type hints.
3. Docstrings (Documentation Strings)
Docstrings are string literals that immediately follow a function or class definition, Docstrings are a great way to explain in detail what our function does, what arguments it takes, any exceptions it throws, what it returns, etc. Wait.
Also, if we use a tool like Sphinx to create online documentation for the code, the docstrings will automatically be picked up and converted to proper documentation.
The following example shows the docstring clay_volumefor a .
Here we can specify what each parameter is, which is more detailed than basic type hints, and we can also include more information about the method behind the function, such as academic references or equations.
Having docstrings is also very helpful when we call functions from elsewhere in the code. For example, when editing code with Visual Studio, you can hover over a function call and see what the function does and what popups it requires.
If we use Visual Studio Code (VSCode) to edit our Python code, we can use extensions like autoDocstring to simplify the process of creating docstrings. The plugin allows us to enter three double quotes and autofill the rest of the template, we just need to focus on the other details that have to be filled in.
4. Readable Variable Names
Many times, when we write code, we don't care too much about the names of variables, especially when we're in a hurry to complete some functionality. But if our code returns a series of variables named x1 or var123, it's possible that no one can understand at first glance what they represent.
In the example below, we have two variables f and d. These meanings can be guessed by looking at other parts of the code, but it will take some time, especially if the code is very long.
If we assign appropriate names to these variables, we know that one of them is the data_file read by the lasio.read() call, and most likely the raw data, and the data variable tells us that this is the actual data we're working with.
5. Avoiding Magic Numbers
Magic numbers are values in code that have a lot of unexplained meaning behind them and can represent constants. Using these in code can lead to ambiguity, especially for those unfamiliar with any calculations in which numbers are used.
Also, if we had the same magic number in multiple places and needed to update it, we would have to update every instance of it. However, the whole process is much easier if the numbers are assigned to properly named variables.
In the example below, we have a function that computes a value called result and multiplies it by 0.6. Through the code, we cannot accurately know the specific meaning of the code
If we declare a variable and assign that value to it, then we have a better chance of knowing what it is. In this case, it is the ratio of clay to shale used to convert the gamma ray index to clay volume.
Summarize
Adding documentation to our code via comments and docstrings can go a long way to helping ourselves and others understand what the code is doing. Indeed, it may feel like a chore at first, but with the use of tools and regular practice, it can become second nature to you.
Click here👇 to follow me, remember to mark the star~
Recommended reading
CDA course consultation