Five essential tips to improve the readability of Python code

There are many methods in Python that can help us understand the inner workings of the code. Good programming habits can make our work more effective with half the effort!

For example, we might end up with code that looks a lot like the image below. Although not the worst, however, we need to expand on some things, such as:

• What do f and d stand for in the load_las_file function?
• Why do we check the result in the clay function?
• What types do these functions require? Floats? DataFrames?

In this article, we will focus on how to improve the readability of your application/script through documentation, prompt input, and correct variable names. Five Essential Tips for Sex.

1. Comments

The first thing we can do to our code is to add some comments to our code, but we should not overuse 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 line 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 variable types are only checked at runtime. Additionally, variables can change type during code execution.

Static typing, on the other hand, involves explicitly stating what type a variable is and it cannot change during the execution of the code.

In 2014, PEP 484 introduced the concept of type hints, later introduced in Python version 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 file name parameter should be of string type
• start_depth parameter should It is a float type, and the default value is None
• This function will return a pandas DataFrame object

We can immediately accurately determine the function needs based on the type hint what and what it will return.

3. Docstrings (Documentation Strings)

Document strings are string literals that follow a function or class definition. Docstrings are a great way to explain in detail what our functions do. what, what parameters it takes, any exceptions it throws, what it returns, etc.

Additionally, if we create online documentation for our code using a tool like Sphinx, the docstrings will automatically be picked up and converted into appropriate documentation.

The following example shows the docstring for a function named clay_volume.

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 a docstring is also very helpful when we call functions from elsewhere in the code. For example, when editing code using Visual Studio, you can hover over a function call and see a popup of what the function does and what it requires.

If you use Visual Studio Code (VSCode) to edit our Python code, you can use extensions like autoDocstring to simplify the process of creating docstrings. The plugin allows us to enter three double quotes and automatically fills in the rest of the template, we only need to focus on the other details that must be filled in.

4. Readable Variable Names

Many times, when we write code, we don’t pay much attention to the names of variables, especially when we are eager to complete certain functions. But if our code returns a series of variables named x1 or var123, no one will be able to understand what they represent at first glance.

In the following example, we have two variables f and d. It's possible to guess what these mean by looking at other parts of the code, but this takes some time, especially if the code is long.

If we assign appropriate names to these variables, we will be able to know that one of them 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 working with.

5. Avoiding Magic Numbers

Magic numbers are values ​​in code that have many unexplained meanings behind them and can represent constants. Using these in code can cause 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 you assign the numbers to properly named variables.

In the example below, we have a function that calculates a value called result and multiplies it by 0.6. We can't know exactly what the code means from the code

If we declare a variable and assign the value to it, then we have a better chance of knowing what is it. In this case it is the clay to shale ratio used to convert the gamma ray index to clay volume.

Summary

Adding documentation to our code through comments and docstrings can go a long way in 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.

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!