The other day, I was looking through my old repositories, and I was surprised by how far I’ve come from when I first started coding 5 years ago.
It is funny to notice some of the things I did and the way I wrote or structured my code that now I would do better.
Image by hitesh choudhary from Pexels
We tend to forget how we started, inexperienced and clumsy, but as we practice, we get better and better. However, we are always focused on how we can be even better. We forget to appreciate the progress we have made, and it becomes demotivating because where we want to be still seems so far away.
I wanted to change this mentality, which is why I started reviewing my old code. Maybe a few years from now, I’ll be writing another post like this so stay tuned!
Now, let’s get to the 5 key lessons I’ve learned throughout my coding journey.
These lessons have helped me write code that is more readable, modular, and testable. And I hope they can help you too.
Write descriptive names, better documentation, and type annotations
More and More I see the importance of well-documented code even for isolated scripts or projects.
Going through my old scripts, I just can’t remember what some of the functions did because they weren’t documented at all, even the names were quite cryptic — another red flag.
It is important to document your code because, after a while, when you have to use them again you’ll spend a lot of time just remembering what each part does and how they are connected.
Documentation is not only for yourself but for others too. Without it, people would need to read each line of your code and figure out what each parameter is.
That’s a huge waste of time.
Even if you’re just starting, it’s a good idea to write your code with the mindset that others might use it.
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.” — John F. Woods
They have:
- A long description of what the code does
- The different parameters it needs, the type of the arguments
- What it returns
- Notes
- Example codes and their output.
It is hard to be so thorough, especially if you have time constraints. I mean we don’t have an army of contributors helping us. So I make sure to include at least a description, the parameters and what it returns, and sometimes example codes.
Type annotations are important as well so people don’t have to guess the type of the parameters the function needs.
def example_func(number: int): # int is a type annotation
pass
You can use AI, like ChatGPT or GitHub copilot, that does it for you.
Learn SOLID principles
SOLID principles are general guides or philosophies on how to write your code so it is easier to maintain, scale, reuse, and test.
SOLID is an acronym that stands for Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Injection.
Explaining what each principle is, would be out of the scope of this story but you can check this YouTube video and channel where he explains clearly each concept with an example.
They were a game changer for me. Coming from a biochemistry background I knew nothing about programming practices and the courses I took didn’t even mention it which is weird because I think they are key in writing quality code.
So you should know about their existence.
Plan your code: Have an outline of the functions and classes you will need
You can save a lot of time if you know which functions and classes you will need and what they’ll do, as well as how they will interact.
Before, I would go directly to coding. I would think about a function or class I needed, do some research, and write it. Then when I wanted to write the next function I would think about how to connect different parts and more often than not I would have to modify some of the code I wrote.
So it was all wasted time, but if you know more or less what you’ll need at the beginning it streamlines the research, the coding, etc.
Put in some work upfront, to save time down the road.
"Coding without a plan is like building a house without blueprints — it might work, but it’s a risky venture.” — Douglas Crockford
Take breaks when debugging your code
There were a lot of times when I would obsessed about a bug and just waste all my time and energy on that.
Then after giving up and doing something else, I would usually come back with fresh ideas on where the bug might have come from.
All that frustration was for nothing.
So when you have a bug that you don’t know how to debug take a break, focus on something else, and then, you might return with new insights on how to tackle it.
“You can’t solve a problem with the same mind that created it.” — Albert Einstein
Write tests for your code and Pip install -e
I started without writing any tests, properly at least.
I would check that each time I wrote something that block of code would work. So I thought, why you would need to write additional code for testing them again.
With time and as my projects grew I understood the importance of testing, because when you change one part of the code you might break something or have some unexpected behaviors, so having a way to automatically search for bugs will save you time.
For small isolated scripts, you probably won’t need it.
The easiest test you can write would be an end-to-end test, where you process the input and see if at the end the output matches what you’d expect.
I do that in my notebooks.
The next step is to write a test for each of your functions or class methods so you can catch errors automatically if you change anything later.
The pip install -e is a bonus.
It installs your library in interactive mode so every time you make changes, you can import the latest version.
Takeaways
It might be overwhelming to learn all of these at once so start small.
- Get used to writing better names and more thorough documentation, and add them to your current projects.
- Then move on to write tests for your code.
- Learn SOLID principles and change your code where you see fit because you can always overdo it.
- Plan your code for your next project, the SOLID principles will help you as well.
Thanks for reading this post
Do you have any additional advice so we can learn from each other?