Help people understand your code¶
Even if you use Pythonic idioms, your code probably won't be perfectly understandable by itself. But with all the time you save by writing code that is more Pythonic, you can spend more time documenting your code. That way other people can figure it out.
Doc strings¶
An analyst has a function that calculates the distance from a given point to the origin in three dimensions.
def distance_from_origin(x, y, z):
return (x**2 + y**2 + z**2) ** 0.5
One option is to say that it is perfectly obvious what this function does from its name and parameters. But your functions are much more obvious to you than they are to other people. "Other people" includes future you. You do not want future you mad at current you for not explaining what your code does.
A better option is to write down explicity what this function does, what kind of arguments you can pass to it, and what kind of value it will return. For example, you might have a text file, or a web page, or a Word doc. Hopefully not a sticky note on your monitor, but even that's better than nothing. Something like:
Calculates the distance from a given point in three dimensions to the origin (0, 0, 0).
Args:
x (float): The x-axis coordinate.
y (float): The y-axis coordinate.
z (float): The z-axis coordinate.
Returns:
float: The distance.
That works OK, but separating your code from your documentation forces people to look in two places. It also means that the built-in help function is mostly useless for learning about your function.
help(distance_from_origin)
Help on function distance_from_origin in module __main__: distance_from_origin(x, y, z)
A better way to document your code is to include the information as a doc string. You can use doc strings with modules, function, classes, and methods that you create.
def distance_from_origin_docstring(x, y, z):
"""
Calculates the distance from a given point in three dimensions to the origin (0, 0, 0).
Args:
x (float): The x-axis coordinate.
y (float): The y-axis coordinate.
z (float): The z-axis coordinate.
Returns:
float: The distance.
"""
return (x**2 + y**2 + z**2) ** 0.5
By including a doc string, people can use the built-in help function to see the information without having to open the source code file.
help(distance_from_origin_docstring)
Help on function distance_from_origin_docstring in module __main__:
distance_from_origin_docstring(x, y, z)
Calculates the distance from a given point in three dimensions to the origin (0, 0, 0).
Args:
x (float): The x-axis coordinate.
y (float): The y-axis coordinate.
z (float): The z-axis coordinate.
Returns:
float: The distance.
Many IDEs will even show the information when you hover over the function name.
Type hints¶
An analyst tries using the distance_from_origin_docstring function, but is getting an error
coordinates = [2, 5, 4]
distance = distance_from_origin_docstring(*coordinates)
info_string = "The point is " + distance + " meters from the origin"
print(info_string)
--------------------------------------------------------------------------- TypeError Traceback (most recent call last) Cell In[15], line 3 1 coordinates = [2, 5, 4] 2 distance = distance_from_origin_docstring(*coordinates) ----> 3 info_string = "The point is " + distance + " meters from the origin" 4 print(info_string) TypeError: can only concatenate str (not "float") to str
The error is reasonably informative, and the analyst can use it to fix their code. But the problem only showed up after the analyst ran the code. It would be nice to get that information beforehand. Type hints are a way to pass information to type checkers and IDEs that can help ensure that you're using the correct types, without having to actually run the code.
def distance_from_origin_typehints(x: float, y: float, z: float) -> float:
"""
Calculates the distance from a given point in three dimensions to the origin (0, 0, 0).
Args:
x (float): The x-axis coordinate.
y (float): The y-axis coordinate.
z (float): The z-axis coordinate.
Returns:
float: The distance.
"""
return (x**2 + y**2 + z**2) ** 0.5
If the analyst has used this function, type checkers like Mypy would have flagged the use of the distance name as incorrect usage. Then the analyst could have corrected their code immediately.
Type hints are well-named. They do not force you to use the right types. They will not cause Python to throw an error if you use the wrong types. They give you a hint that you are not using a value correctly. For example, the distance_from_origin_typehints function executes successfully when you pass it a complex number as an argument, even though a complex is not a float.
coordinates = [2j, 5, 4]
distance = distance_from_origin_typehints(*coordinates)
info_string = f"The point is {distance} meters from the origin"
print(info_string)
The point is (6.082762530298219+0j) meters from the origin