manage your python dependencies with conda
#python #conda
Learn how to manage your Python version and libraries.
oct 11th 2023
Have you ever returned to a project you hadn't worked on in a while and had no idea what you were doing? Or maybe you've been working on a project with a team, and you have no idea what your teammates' code does? If you have, then you know how important it is to write readable code.
We will be using this simple code snippet as an example throughout this post. This code defines a class called Foo with two methods: bar and baz. A priori, it is not clear what this code does. We can make it more readable by following the tips below.
class Foo:
def __init__(self, a, b):
self.a = a
self.b = b
def bar(self):
return np.pi*np.power(self.a, 2)*self.b
def baz(self):
return 2*np.pi*self.a*self.b + 2*np.pi*np.power(self.a, 2)
The first step to writing readable code is to use descriptive variable names.
There is a famous quote by Phil Karlton that says, "There are only two hard things in Computer Science: cache invalidation and naming things". The seemingly simple task of choosing clear and meaningful names for variables can be surprisingly challenging. In our example, a piece of cake:
Making these changes, our code becomes much more readable:
class Cylinder:
def __init__(self, radius, height):
self.radius = radius
self.height = height
def volume(self):
return np.pi*np.power(self.radius, 2)*self.height
def area(self):
return 2*np.pi*self.radius*self.height + 2*np.pi*np.power(self.radius, 2)
Always try to write procedural code.
Try to divide the code into as many steps as necessary. You are not a better programmer for writing more one-liners. It is often more beneficial to be clear than the minuscule optimization you might achieve.
In our example, despite being a simple piece of code, I hope the point is clear. We can divide the area method result into two calculations: one for the lateral area and one for the base area. This further explains what the code does and makes it more readable.
class Cylinder:
def __init__(self, radius, height):
self.radius = radius
self.height = height
def volume(self):
return np.pi*np.power(self.radius, 2)*self.height
def area(self):
lateral_area = 2*np.pi*self.radius*self.height
base_area = 2*np.pi*np.power(self.radius, 2)
return lateral_area + base_area
Python is an interpreted language, meaning that it is a loosy-goofy language. If you pass to the cylinder constructor a boolean variable, Python will not even blink. The program will just panic during runtime, which is sometimes very annoying.
To avoid these kinds of mistakes, one would normally use a Language Server Protocol (LSP) to get a real-time feedback on errors. There are many LSPs for Python, like Pylance or Pyright, and they are really nice. LSPs will try their best to catch these errors, but they are not foolproof.
Type hinting has a double purpose: to help the LSPs do their work better and to help the programmer understand the code better.
In our example, we can add type hints to the arguments of all methods, the class' attributes, and the variable declaration in the area method. In the event of passing the wrong argument type, our LSP will warn us.
class Cylinder:
def __init__(self, radius: float, height: float) -> None:
self.radius: float = radius
self.height: float = height
def volume(self) -> float:
return np.pi*np.power(self.radius, 2)*self.height
def area(self) -> float:
lateral_area: float = 2*np.pi*self.radius*self.height
base_area: float = 2*np.pi*np.power(self.radius, 2)
return lateral_area + base_area
Comments are not for documenting your code.
Comments are for explaining why you did something, not what you did. If you need to explain what you did, then you should refactor your code to make it more readable.
In our example, there is not much to say, but to make the point clearer, we could annotate the choice of using NumPy instead of the built-in **, for example.
class Cylinder:
def __init__(self, radius: float, height: float) -> None:
self.radius: float = radius
self.height: float = height
def volume(self) -> float:
# np.power is faster than **
return np.pi*np.power(self.radius, 2)*self.height
def area(self) -> float:
lateral_area: float = 2*np.pi*self.radius*self.height
base_area: float = 2*np.pi*np.power(self.radius, 2)
return lateral_area + base_area
Docstrings are for documenting your code.
The ultimate way of documenting your code is to use Docstrings. Docstrings are strings that are placed right after the declaration of a function, class or method, and are used to describe what the function, class or method does. The main advantage of using Docstrings is that your LSP will show them to you, saving you lots of time checking external documentation.
It makes the code much chunkier, so I recommend using them for objects exposed by your API.
class Cylinder:
"""
A class to represent a cylinder.
"""
def __init__(self, radius: float, height: float) -> None:
"""
Parameters
----------
radius : float
The radius of the cylinder.
height : float
The height of the cylinder.
"""
self.radius: float = radius
self.height: float = height
def volume(self) -> float:
"""
Computes the volume of the cylinder.
Returns
-------
float
The volume of the cylinder.
"""
# np.power is faster than **
return np.pi*np.power(self.radius, 2)*self.height
def area(self) -> float:
"""
Computes the area of the cylinder.
Returns
-------
float
The area of the cylinder.
"""
lateral_area: float = 2*np.pi*self.radius*self.height
base_area: float = 2*np.pi*np.power(self.radius, 2)
return lateral_area + base_area
Writing readable code is a skill that takes time to master. It is not easy to write code that is both readable and efficient. But, as with everything in life, practice makes perfect. The more you write code, the better you will get at it.
Thanks for reading!
If you liked this post, you might also like