A 3 Point Guide To Writing Better Code in Python
Writing rich, readable code is extremely easy, if you keep some of these simple things in mind for your next Data Science project.
We all want to read code that we can understand in a single read. Any new API we discover, an open source library that we want to explore or a new project codebase that we’re ready to expand, the first thing we need is to understand what’shappening and why it’s happening.
If your colleague has no problem reading and implementing your code, it’s because you followed some basic practices to make sure no time is wasted in trying to decipher the meaning behind a variable, a function or a class.
Writing neat code not only helps your teammates, it also helps you out at a later date when you revisit that particular project and read your own code.
Here, I’m going to talk about five tiny things that pose a significant advantage in that regard and tend to increase your productivity and workflow like a pro.
Let’s get started 👇
Start using docstrings to document today!
The most popular way to make sure anyone who reads your function comes to know everything it does before even entering the function is through docstrings.
They’re quite useful in every function and class, and you must have seen these in every library that you’ve ever used.
There are numerous ways to write them, the most popular one being the Google and Numpy formats.
Three fundamental things to write in a function or class are:
Description of what it does
Arguments it takes with their types, and finally,
The objects it returns with their types.
If you’re using VSCode, it’s extremely convenient to install an extension to easily generate the docstring skeleton that you’ll only need to fill out later for your function or class.
You can use either Python Docstring Generator or the AI Python Docstring Generator. In my experience, both of them work really well.
Docstrings are the means to write clean, well-documented functions that follow best practices and are a delight to any developer (and yourself) that reads your code.
Concise coding concepts!
Here are some easy ways that I’ve always used to achieve brevity in my Python code without compromising the logic.
Use multiple assignments whenever possible!
The idiomatic manner of writing Python scripts never gets old. You can significantly make your code more concise with this method.
Notice how cleaner it looks this way, doesn’t it?
Use Inline conditionals
If your condition has a one-statement implementation, switch it to one line.
If you have an else statement too, use this format:
This is also called the ternary expression format.
Use walrus to delete unnecessary assignments
You don’t need to have separate statements for assignment and if statement. Combine them smartly.
The regular way:
The better way:
Reduce indenting as much as possible
Hard to read code in Python can result from various cases like unnecessarily nested if statement and too many unused variables.
Let’s look at an example.
Here, we’re calling our function from within an if statement that’s checking one single condition everytime it has to call the function. There’s a better way to do this without using that last indent.
Using the continue keyword:
I call this the process of elimination. This means — check only the condition in which not to call the function, otherwise call the function.
These are the only a few example of ways in which you can use Python’s powerful syntax and expressions, you can explore much more in order to make your code more concise and easy to read!
If you’re working on a medium-scale project, multiply these small changes in your code by a couple hundred times and you have something significantly better than the one you started out with!
Use descriptive names everywhere
A long, descriptive name is better than a short, enigmatic name. — Robert C. Martin
Don’t be hesitant to use long function or variable names in your code. Short and vague names are much harder to read and understand what they’re being used for just by looking at them.
One glance should be enough for a developer to know what it’s supposed to be doing.
For instance, consider a function that you’ve written for converting some csv into excel and exporting and saving it to disk.
You can use a name like —
excel()and it would be a terrible idea. A developer will have to go into the function and actually read the lines (if you’ve written them properly) to understand what the function should be doing.Instead, use a name like —
convert_to_excel_and_export() ,which readily conveys the information to anyone who takes one look at the function.
This applies to not just functions — to classes and simple variable names too.
And remember — what cannot be explained with names, do them with comments. Comments tell the story behind your code. Use them strategically.
Small comments placed here and there always save a load of headaches later on.
Concluding…
As parting words, I would say — always try to write minimalistic functions.
When writing a function, make sure to keep it specific to the task you want it to perform. Delegate every other thing to other functions.
It’s very important to know that complicated functions are a complete waste of time. Your colleague who wants to reuse your code will not find it easy when she looks at your function and tries to understand exactly which part to use and which part to let go.
Therefore, just write a function to do one precise thing and then document it well. You’re typically saving hours, not just minutes of work in the long run for both yourself and your team that way.
All the code and resources for my articles reside here. ⭐️ the repository and check them out!
Follow me in here if you find this article helpful. Every week, I share what I learn in the world of Data Science and Programming in general.
A couple other articles of mine that you might love to read:
The Reusable Python Logging Template For All Your Data Science Apps