After working for more 10 years as a software engineer I’ve realized it doesn’t change. You might develop some techniques to prevent some from happening but others will show up, it never ends.
In order to learn from those mistakes and try to avoid them in the future you can develop a bug log. We’ll see here what that is and how it works but I promise it helps.
I recently introduced this idea at Buffer where I’ve been working for almost 5 years now and I thought it’d be cool to share it publicly here as well.
The (endless) cycle of software development
1. Work on a new feature
2. Fix bug(s)
3. Go back to 1.
Sometimes you might focus on only developing new features or only fixing bugs but those are the biggest chunks of your work if you’re building software.
I think we focus a lot on the how to develop more effectively new features: using the latest framework, text editor or IDE, a new programming paradigm, etc. and when we build something new again, we try to apply the things we’ve learnt and improve.
On the other hand, when we fix a bug, we tend to do it as quick as possible and then move on to something else, almost like it didn’t happen in the first place. Very few people spend any time trying to learn new debugging techniques instead of learning the latest framework that came out.
If we spent more time reflecting on those errors, learning from them and understanding where they came from we could improve a lot.
Documenting a personal mistake
I’ve started to document those bugs, only the ones where I was the only engineer who did it so I can totally understand the context and reflect on what I personally did.
There are many different ways to do this, but I thought it’d be cool to have one place where I can gather all of them and search in the future for references and patterns. I don’t know if the term already exist but I called it the “bug log”. 🤷♂️ 😅
What’s a bug log?
A bug log is a collection of your past introduced bugs with different sections for each bug:
- The context where the bug was introduced and what you were trying to achieve (fixing another bug, adding a new feature, etc).
- Why the bug happened. What was wrong in production that made you realize that there was a bug.
- How you fixed it.
- The lesson you learned afterwards. A summary of what you’ve learned in the process.
These sections are the ones that work for me, but feel free to adapt them to your needs if you want to start a bug log.
An example of an entry in the bug log
# Context
When working on this JIRA ticket ____, trying to track an action on the backend,
I merged the pull request and it failed in production in a certain environment.
- Link to ticket: ....
- Link to pull request: ....
# Why the bug happened
The environment variable was not set in one of the environments and that caused
an error in production.
# How I fixed it.
I created the new environment variable by doing X and Y.
# Lesson learned.
When using an environment variable make sure it's available in all the environments
before deploying.
As you can see it’s not anything formal and it’s just for you so feel free to use the format and tone that makes the most sense.
The nice aspect about this is that if I see this becomes a pattern like if I introduced more than one bug of this type in the next year or so, I can work on a better solution. For example, a parser that compares the env. variables used in a new pull request with the ones that are in production.
Where do I store the bug log?
I’ve become a big fan of Notion and I’ve added it there so other team members can see it but it could be anywhere, any note-taking app or even a Github repo with some markdown files could work.
What to do with the “lesson learned” sections?
Something I’ve realized is that by summarizing in one sentence the bug I introduced and why I can easily reflect and learn the lesson. I’ve taken one extra step to not forget it for the future so I use Anki, a solution for reviewing cards from time to time, helping you learn what’s in the card.
I used it before for other purposes but I created a new collection for this. What I do is creating a card whose front is the situation I faced when I introduced the bug and the back is the lesson learned. For example, here it’d be:
Front
--------
What should I do when I use an environment variable in the code?
Back
--------
Check by doing X/Y if it's set in the right environments.
Here’s how it looks in Anki:
This will reinforce my learning and it’s easier that I remember it in the future. It can also include some code samples so you associated the situation to new code that you’ll be modifying in the future.
I’m a big fan of Anki and how it can help you improve as an engineer so I’ll write an article about it soon.
Repeating past mistakes
The other thing I do is before filling a new entry, I can try to search in the log something similar. Sometimes that helps me understand if I tend to make the same kind of mistakes.
I hope this was useful to you! Do you have any thoughts or feedback? Let me know on Twitter! 😉