Five essential tips to improve the readability of Python code

Translator | Zhao Qingyu

Reviewer | Sun Shujuan

Do you often look back at the code you wrote 6 months ago and want to know what is going on in this code? Or Taking over a project from someone else and not knowing where to start? This situation is relatively common for developers. There are many methods in Python that help us understand the inner workings of code, so when you look at code from the beginning or write code, it should be easier to continue where you left off.

Here I will give you an example. We may get the code as shown below. This is not the worst, but there are some things we need to confirm, such as:

• What do f and d represent in the load_las_file function?
• Why do we need to do it in the clay function? Check the results?
• What type do these functions require? Floats or DataFrames?

In this article, I will cover 5 basic tips on how to improve the readability of your application/script through documentation, prompt input, and proper variable names. .

1. Comments

The first thing we can do to the code is to add comments to certain lines, but be careful to avoid commenting too much. Comments need to explain why the code works, or why something is done in a certain way, rather than how it is implemented. Comments in Python are usually completed using the pound sign (#), which can span one line or multiple lines.

# Comment using the hashtag
# Another comment using the hashtag

For multi-line comments, we can also use 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 how certain lines of code work and why:

2. Display Type typing

The Python language is dynamically typed, which means that variable types are only checked at runtime. Additionally, variables can change type during code execution. Static typing, on the other hand, involves declaring the variable type explicitly and cannot change during code execution.

In 2014, PEP 484 introduced the concept of type hints, which was subsequently introduced into Python 3.5. This allows you to declare variable types explicitly. By adding type hints, you can significantly improve the readability of your code. In the following example, we can see:

• Requires two parameters
• The type of the parameter filename is a string
• The type of the parameter start_depth is a float type , and the default value of this parameter is None
• This function will return a pandas DataFrame object

According to the type hint, we can know exactly the function What is required, and what it will return.

3. Documentation string

The documentation string is the string immediately following the function or class definition. Docstrings are a great way to explain in detail what a function does, what arguments it takes, what exceptions it will throw, its return value, and more. Additionally, if you use a tool like Sphinx to create online documentation for your code, the docstrings will be automatically extracted and converted into the appropriate documentation. The following example shows the docstring for a function named clay_volume. Here we can specify the meaning of each parameter. This makes it more detailed than basic type hints. You can also include more information about the methodology behind the function, such as academic references or equations.

#Document strings are also very helpful when we call functions elsewhere in the code. For example, when writing code using Visual Studio, you can hover over a function call and see a popup showing what the function does and what it requires.

If you use Visual Studio Code (VS Code) to edit your Python code, you can use extensions like autoDocstring to make the process of creating docstrings easier. You can enter three double quotes and the rest of the template will automatically fill in. You just need to fill in the details.

Tip: If you have declared types in the parameters, they will be automatically selected.

4. Readable variable names

Sometimes, when you are writing code, you don’t care too much about the names of variables, especially when time is tight. However, if you go back and look at the code and you find a series of variables named x1 or var123, you may not understand at first glance what they represent. In the example below, there are two variables f and d. We can guess the meaning of such variables by looking at other parts of the code, but this can take time, especially if the code is long.

If we give these variables appropriate names, we will be able to know that one of the variables is the data_file read by the lasio.read() call, and is most likely the original data. The data variable tells us that this is the actual data we are dealing with.

5. Avoid magic numbers

Magic numbers are values ​​in code that have an unexplained meaning behind them and can be constants. Using these in code can cause ambiguity, especially if you are unfamiliar with using numbers in calculations. Furthermore, if we have the same magic number in multiple places, when it needs to be updated, we have to update every instance of it. However, if such numbers are assigned a suitably named variable, the substitution process becomes much easier. In the example below, we have a function that calculates a value called result and multiplies it by 0.6. What does this mean? Is it a conversion factor? A scalar?

If we declare a variable and assign the value to it then we are more likely Know what it is. In this case, the ratio of clay to shale is used to convert the gamma-ray index to clay volume.

6. Final Code

After applying the above tips, our final code now looks cleaner and easier to understand.

7. Summary

Adding descriptions to your code through comments and docstrings can help you and others understand what the code is doing. It may feel like a chore at first, but with the use of the tools and regular practice, it will become second nature.

Original link: https://towardsdatascience.com/5-essential-tips-to-improve-the-readability-of-your-python-code-a1d5e62a4bf0

Translator’s introduction

Zhao Qingyi, 51CTO community editor, has been engaged in driver development for many years. His research interests include secure OS and network security fields, and he has published network-related patents.

The above is the detailed content of Five essential tips to improve the readability of Python code. For more information, please follow other related articles on the PHP Chinese website!