Debugging tips for beginners
Lots of things can go wrong — here’s a checklist.
Debugging mentality
I don’t think this is talked about enough.
When I first started coding, I cried a lot. And it wasn’t my first time working with a computer. My background is in applied math and statistics, so I’ve written my share of if-statements, loops and functions using software like Matlab and R.
But things like trying to execute commands on the terminal or trying to get an app to show up in a browser left me feeling so frustrated I cried.
It sucks to try working through a beginner level tutorial, painstakingly following each step as perfectly as possible, only to get error message after error message. What happened? Maybe there was a typo in your code. Maybe there was a typo in their code. Maybe there’s something they assumed you already have downloaded, and you don’t have it downloaded. Maybe you did download it, but it was the wrong version. Maybe your file isn’t in the right folder. Maybe you’re not entering commands within the correct directory. Maybe the tutorial was done using an outdated version of a package, and now it doesn’t work that way anymore. It could be countless other things.
It makes it feel really hard to get started when there are mistakes at every turn. I felt like I was doing something wrong, or that this field is particularly confusing (the jumbled mess of resources online is both a blessing and a curse), or maybe I was crazy to even try this in the first place.
Turns out this is all normal. No, there’s nothing wrong with you. Yes, things do get easier. You’ll learn from every single bug and error that you get. Eventually, you will start getting bugs and errors that you’ve tackled in the past, and you’ll remember how you overcame them. It’s a very rewarding feeling.
Things get easier. For the most part, the bugs and errors become fewer and farther between, and easier to tackle. However, I don’t think they ever fully go away.
It turns out some of the best programmers are the ones who embrace debugging and enjoy it. Once I found that out, I felt so relieved, and not because I enjoyed debugging. I felt relieved because I thought all the bugs I was getting were abnormal for a beginner programmer. I thought they were little roadblocks taunting me and calling me a failure. Turns out they’re just a normal part of programming. Suddenly it became more enjoyable.
Things go wrong. Things don’t work. Things get outdated.
Take a deep breath. It’s a learning opportunity. A scavenger hunt through your code, computer and online help forums to find the tangle in the knot and work through it. Once I chose to embrace this and learn to enjoy it a little more, coding became so much less stressful and a lot more fun. I encourage you to try it if you are dealing with similar frustrations that I was.
Debugging methods and tips
Copy your error into a search engine
Yes, this is pretty much the first thing to try, especially if you are a beginner. I’ve gotten to the point where sometimes I get bugs that I’ve seen before, and so I know how to solve them without searching. Or, I understand a little more about how to read the error messages in a helpful way. But when in doubt, search it. There will hopefully be lots of answers online for how to solve this. And apparently, all programmers do this. It’s not cheating!
Search the error within this content
I tried my best to include almost all the errors I’ve received while running through these examples, so if you have an error and you don’t see it in the section you’re on, there’s a chance I might talk about it in another section. If you’re reading my beginner programming book online or in an online-format, you can use Control-F to see if it shows up. If it’s too much work on the website with all the different pages to search through, then I put a search engine on it, or you can use site:miuminati.com in google to filter your results, if searching without filtering isn’t getting the job done either.
Check for typos
This has been the cause of many issues for me at the beginning. Sometimes it was a mispelling or misplaced parenthesis, and sometimes I had named something incorrectly. For example, sometimes when I follow tutorials I come up with my own names instead of using the names in the tutorial. Then, at some point, I blindly copy and paste code from the tutorial, which refers to something by a name that they defined, but I called something else. Now the code doesn’t work. Or, I might call a namespace the wrong name, typing out something at the beginning of the file that doesn’t match the file name. Another common typo that can happen is with hyphens - and underscores _. In Clojure it’s typical to name things using hyphens, such as cool-app, however with the JVM they must be labelled with an underscore instead, such as cool_app. This is also the case for Postgres and SQL. In this book the example we do contains a hyphen so that you can clearly see which circumstances require you to switch to an underscore.
Typos happen, and it’s worth checking for them everywhere you can think to look. And if you really don’t know, you can post a snippet of your code online to some help forum and maybe someone else will spot it. Sometimes if you look at the same thing long enough, the errors are harder to spot. Printing things out and reading them backwards are two more ways to catch typos if your eyes are glazed over from looking at the same lines on your computer over and over again.
Check the versions
Generally I get error messages when I don’t have the right version of something, and it’s as simple as changing the version number in your project.clj or package.json files.
Another thing to check is whether your error is actually due to an error in the version of a dependency you are using. The libraries and deps we use are written by humans, and humans make errors sometimes. This has been the case for me a small handful of times, so it’s worth checking out. Generally I’ve caught this by searching online for the exact error message I’m getting, and there might be a back and forth on the github page of one of the libraries you’re using about that exact error. If that’s the case, read the page to see what solution was reached, or ask someone online for help.
Sometimes, I’ve done tutorials that used libraries that are no longer being maintained. One way around this is to try to stick to recently published tutorials and books. However, it is something that happens. When in doubt, I tend to reach out to the Slack channel to ask what library people tend to use instead of the one that is now discontinued. Then, see if you can find resources on how to implement that library.
To avoid this happening with my book, I plan to publish everything online. This way, the pages can be edited or achived over time and new information can be added to keep things current, and comments can be added if anyone has an error or question.
Check your downloads
Is there something you’re supposed to have downloaded? Check the prerequisites again, and their version numbers. There might be some that are assumed, but not listed. It might take a little digging to find them. For example, I had no idea I had to have Node.js downloaded in order to use Clojurescript. I didn’t even know what Node.js was. Many different books and tuturials will have different prerequisites, and some may assume things that others don’t. I’ve made my list of prerequisites as robust as possible, testing out everything by starting from scratch on an old macbook.
Check line by line
Go back to where things do work. Now try adding the broken code in, line by line. Where does it break?
You can also look at your namespace and see what other namespaces it relies on. Are there any namespaces that should be required, and aren’t? Is everything in the correct location?
Test the function that isn’t working. Does that function rely on any other functions? Are they working?
One thing I like to do, in order to have a save-point where I know things work, is to create a copy of my project folder any time I’m about to create a new feature or make big changes to the code. This way, no matter what I do to screw things up, I can go back to the previous version where things worked, and I can create another new copy, and start adding things in again to see where it breaks.
Test individual pieces
Related to the previous point. This time we are thinking about the code in chunks instead of lines.
Check the database. Is that part working as you expected? Now what about the back-end? What about the front-end? Something wrong in the database can screw things up everywhere. This is where the terminal can help you. You can use psql commands to see if the database is responding as expected and has all the tables and columns it’s supposed to, as well as test how the back-end functions are working. Generally with the front-end, I can see the changes happening in the browser as soon as I make them, so I don’t use the terminal for that.
Within each section of code, the database, back-end and front-end, check that all the functions and definitions related to your bug are giving expected behavior.
Isolate the issue in a trivial example
Create a new, very basic project and try adding the new feature or design. Can you get it to work here, in an isolated setting? If you can, that might help you identify the issue with the more complicated project through a process of elimination, or by comparing the two sets of code. At the very least, it can help reassure you that at least you can get it to work somehow.
Ask questions
If you’re stuck, or even before you get stuck, ask for help! You can ask me for help, you can post questions on this book’s website (leave a comment on the part you’re stuck on), you can ask slack, you can ask stack overflow, you can ask the clojure subreddit, and so on.
I’ve learned so, so much by asking questions. I highly encourage you to ask. No question is too trivial. Even if it seems trivial, we all make silly mistakes sometimes. And, I will likely see it as an opportunity to make my content even more clear and fleshed out. So it benefits everyone to ask questions!
Conclusion
Learning to code can feel overwhelming. Hopefully it’s a little less intimidating now that you have lots of tools at your disposal for solving errors. Bugs happen, and every single bug is just your code trying to teach you something. If you can embrace them as learning opportunities, it can make the whole process more enjoyable and even fun.
Seeking extra help?
Check out my living textbook full of beginner tips at miuminati.com where you can read more content just like this and leave comments or post your own content! You can also watch videos explanations of all this and more at the youtube channel.
