Getting Unstuck
Estimated Reading Time: 5 Minutes
Disclaimer: This blog post is mostly for my own reference, and to practice technical writing.
Have you ever gotten stuck when trying to tackle something entirely new? You have a vague picture of where you are and where you want to be, but everything else in between feels like an ugly black box full of hidden complexity that you don’t understand (even attempting to read a full sentence of documentation can be a trying task if you don’t understand all the unfamiliar terminology being used).
That’s why it’s important to learn how to learn – to effectively unstick yourself, especially when there isn’t anyone around to help you.
Here are the steps I’ve followed, in order, when trying to get unblocked. These steps are specifically optimized for getting unstuck quickly and efficiently, but that shouldn’t be where you stop - try to really understand the system you’re working on. This will save time later on, especially if you’ll be working in the same codebase in the future.
1. Run test code.
If what you’re trying to debug has tests, run them! The stack traces can lead you to where the problem might be. If there are no tests, write some!
Other tactics include (but are not limited to): putting print statements everywhere to figure out where in the program things went wrong, refactoring your code to make reasoning easier, looking at any logs or metrics you may have, or running a debugger to step through your code. (Although the last suggestion may not scale with larger or more complicated projects.)
2. Shamelessly search everything.
If you think you’ve identified the error or have a basic understanding of what to search for, other people may have faced the exact same problem as you are facing. Search on Google for a solution or any leads! (Be aware that Google searching can also lead you down the wrong path.)
If your organization uses Slack, Stack Overflow, Notion, or any database of past answered questions specific to the software you’re working on, now would be the time to utilize those resources. If you find a solution through your search, try to understand it as thoroughly as you can (as time permits) before moving on.
3. Look at existing examples.
Oftentimes you can look at old PRs or other examples of what you’re trying to accomplish and pattern match.
A lot of engineers use pattern matching to unblock themselves briefly without truly grokking the code they’re copy-pasting into their programs. Sometimes it’s necessary in the interest of time (or impatience), but more often than not this practice leads to bigger problems down the line when those engineers are forced to debug code they never really understood, with assumptions they’ve made about the code that are likely incorrect. I’ve been guilty of this in the past, unfortunately.
Don’t just stop at pattern matching. Try to figure out what is actually happening in the code that you’re writing.
4. Read the documentation.
RTFM. Do the reading. Slow down. You may have a bad habit of just skipping to the part that you need to know. If you have the time, it doesn’t cost you to read the whole thing.
If you’re having trouble understanding a sentence, slow down and focus individually on each word you don’t understand. Try to understand those terms first, and then go back and reread the sentence. Have patience. Learning takes time and you won’t always get it after the first read, even if you’re the most intelligent human being in the world.
5. Read the code.
If reading the documentation wasn’t as helpful as expected, or if there’s little or no documentation for the software you’re working on, try reading the source code. Focus on where functions are being called and what each function is doing. Take notes or draw diagrams in a notebook if it makes it easier for you to understand how moving pieces fit together. It may help at this point to identify or understand which moving piece the error is originating from, either by testing each piece sequentially, or turning things off and on again to see what works.
This step may not be as helpful, especially if the code is poorly documented/commented or organized in a way that doesn’t make sense to people who lack the necessary context.
6. Ask for help.
As important as the skill of self-learning is, an almost equally important skill is knowing when to stop banging your head against a brick wall. Sometimes the problem is just too insurmountable for you to solve on your own. Maybe you lack the necessary history and context that another engineer would know, or you’ve made an assumption that led you down the wrong rabbit hole for hours.
You need to know when to stop and ask for help. Don’t expect other engineers to ask if you need help, either - they may be afraid to patronize you. Don’t be afraid to ask for help when you need it. Sometimes I get scared that people will think I’m stupid for not being able to figure something out, especially if I’ve been stuck on that problem for awhile. If you’ve made a reasonable effort and you’re still blocked, it’s smarter to get someone’s help than to remain stuck for that much longer. Generally, I try to ask for help from a more experienced engineer if I’ve been blocked for more than one or two hours.
Some senior engineers have told me that it can be difficult to fill in the gaps for someone whose context they no longer have. It’s like a rocket scientist trying to teach math to a fifth grader. They don’t remember what it’s like to be a fifth grader anymore. It is easier for them to teach when they assume you don’t know anything, and then ask you what you already understand as they’re teaching you.
Ways to help your fellow engineer better help you:
Being able to clearly identify when you don’t understand something and being able to admit it.
Having specific and detailed questions to ask.
Clearly communicating concepts that you already know or making connections between the new things they’re teaching you and what you already know.
Explaining the solutions you’ve already attempted, instead of asking for help by saying “I don’t know what’s happening or what this is doing.” and expecting the other engineer to do all the detective work for you.
You can do it! Getting unstuck gets easier as time goes on and you develop more of an intuition for the domain you’re working in. :)