After a long hiatus, I’m back today with a post on how to develop the debugging skill. If you’re new to programming, we refer to the process of finding and solving errors in the code as “debugging”. It can be difficult to acquire this skill as a newbie when you have no idea what you should even look for. This post will help you out with a few hints.

Why should I learn debugging?

Most people who attend a programming class for the first time get quite the culture shock. Often, their identity had encompassed something like “good with computers”. Then they see what it’s actually like to interact with a computer as a superuser, i.e. someone who interacts with the computer not only in the way intended for users by product designers, i.e. mostly the Graphical User Interface (GUI). Often computer usage the superuser way means it’s entirely text-based (although you can learn the first steps to programming with visual languages too, like the PocketCode app’s Catrobat or MIT’s Scratch). This scares a lot of people (though really there isn’t any reason to feel intimidated, you can do it! You only need to get used to it).

And it turns out that being more social media savvy than your grandma isn’t enough to feel like you have “digital literacy” anymore (maybe I should discuss this topic at some point in the future).

So anyway, reasons why you should learn to debug include the following:

1. It’s absolutely necessary, an inevitable part of programming. Literally 90% of programming is actually debugging. (I am not exaggerating, there are studies on this).
2. Your debugging ability shows your skill level as a programmer and your perseverance at debugging is a great predictor if you can become a programmer. This is not determined by some innate talent but much rather by your willingness to undergo the humbling, hour-long, tedious process of failing over and over again that we call debugging. If you are too proud to dive into your own failures, you will never learn to program. (Sorry!)

Resources to check out if you’re completely new to programming:

1. Algorithms, Variables, Debugging? Intro to Programming Concepts
2. The “Learning to program” category
3. Learning to program: Failing fast and error messages
4. Learning to program: What to do if the program doesn’t compile
5. A blogpost and the wikipedia page on debugging

But now, let’s get to today’s post:

How to develop the debugging skill

Debugging is like an intuition. And I remember when I didn’t have it yet, I had no idea where to look when something didn’t work. Likely, most people who are really good at debugging won’t be able to tell you exactly how to learn it from the top of their heads. I think nobody can. It’s not a linear process. But there are a few places where you can start looking.

 

It’s likely the small stuff: (missing) braces, semicolons, typos and the like

Like the heading says, most problems are actually typos or missing signs like braces or semicolons. Misspelled variable names, etc. These may sound innocuous but don’t be fooled: They can be treacherously tricky to find and very illusive! Don’t underestimate them!

However, for these types of errors (syntax errors), you will usually get an error message indicating where the program failed. This is not necessarily the place where the error occurred but at least you have an idea where to start looking for it. It’s much more obscured when the program is working correctly (from the perspective of the computer) but it doesn’t do what you think it should be doing.

What to look for in LaTeX / How to react to error messages

In LaTeX, always check the curly brackets. Read the error message carefully and try to understand it. What seems to be the problem, in which line and why? If you don’t understand the error message, copy the whole thing in a search engine prefaced with ‘latex’ (or any other programming language you have encountered the error with) and surely help will come up.

Just follow these steps without panicking and you’ll be fine.

In LaTeX bad package loading order can be the problem also. This is a bit more tricky. Have fun finding those if you don’t know about this possibility or known problems beforehand. Like, for example, enumitem and beamer don’t cooperate with each other. The loading order can be screwed. It’s really a matter of experience to know these things. Please don’t expect to understand this stuff at the beginning. You don’t need to. Just try out solutions suggested online.

But there are some other tricks you can use to increase your chances at exterminating your bugs…

 

Comment stuff out

If all goes wrong, comment stuff out to locate around where the problem is. This will make the situation a lot less horrible. Often, you will find that the problem is really very localized, so not all is lost. This is usually a huge relief as this will not only allow for more targeted bug hunting, it will also give you the possibility of throwing out the bad piece of code in case you really need your working code soon. There will be a part missing, of course, but a missing part is better than having nothing at all to show for. 

So when is the point where you should stop your aimless searching, put on the full body armour (because now things are getting serious!) and start commenting things out, you ask? Well, after the first mental breakdown or so and/or not finding the problem after 20 minutes of looking frantically usually is a good time. A good time for a break I mean. Make tea. Honestly. And then sit back down, take a deep breath and start commenting things out or removing parts of your code in another document. Try starting with the area where you expect the problem to be or which you remember to be the last place you likely last edited before the problem arose.

When working in LaTeX, be sure to compile regularly. When I don’t work in the Overleaf online editor which automatically re-compiles sometimes, it can happen to me when I’m really in the zone with my writing that I forget to compile for a long time. Then there’s a mistake and I have literally no clue when or where I might have introduced it.

Ergo: Check whether your code works often. That way you can still remember the changes you introduced before the problem came up and can tackle them in a much more organized way.

 

The utter terror of having nothing to show for / submit tomorrow because your program doesn’t work

I think a big part of the utter terror of bug-ridden programs, especially when they don’t even compile, is that you might have nothing to show for in case you need to tomorrow. The first weeks of programming taught me that programming is not something you should put off until the last minute. Nothing is more stressful than the rush of adrenaline you get when you know that your deadline is nearning and your code doesn’t work. Debugging can be done in 5 minutes if you happen to come across the error rightaway (this usually happens after taking a break in nature, a shower, cooking, in short taking off time from work which might be a luxury you can’t seem to afford right now). It can also take hours and hours. 

Don’t do major programming the day before the deadline. That last day is for fixing last minor errors (submit to version control system first before you might break the running system, more on that, see below). It’s for making sure your code is understandable, formatted nicely, follows coding standards. For checking that unnecessary comments or commented-out code are removed, everything is documented, etc. 

Maybe also testing with different systems and edge-cases in case you haven’t done that before (though if your progam isn’t tiny, the last day also seems a bit too late for this). In case you fucked up here, learn from your mistakes and do better next time.

I used to finish all my homeworks at the last minute. Programming is what taught me to (forced me to??) finish stuff ahead of time. And believe me, it will save you tons of near heart attacks. Protect your health, don’t put  programming off until the last day!

Prevention: Using Version Control Systems

However, if you really need your working output tomorrow, debugging alone might not be enough. What you need is a system to prevent disaster from striking in the first place. (My condolences if this is already too late for you! You know how to do better next time. Maybe you’re in luck and the undo button will do the trick for you. Then please save both your latest version and the “undone” one, just to be safe.) I have had to resort to the undo button more than I care to admit. It has saved me countless times but relying on it has caused almost more chaos than it has spared me from. Use this wisely and only if there’s no other choice. Don’t rely on the undos going back far enough into the past that you can actually get back to a working state of your program. 

Be sure to save your changes to version control regularly (some of the more popular systems include git, Github and SVN in case you’re not familiar with VCS). That way, you can always go back to a previous working state should the worst case scenario happen that you really can’t find the mistake in time. Version Control will save your ass, so make sure to add your code to it at appropriate moments. I never do that or at least not at the appropriate moments. Which is a mistake, believe me! Don’t be like me, it’s a really shit experience you don’t want to have.

(I personally benefit a lot from smart software like the Overleaf editor which makes good decision for me.)

 

Get good error management

Some of the tools you work with will have excellent error management capacities. Others may not.

In LaTeX, TeXmaker, for example, has really unhelpful error management, I think. It will often indicate some other line than from where to problem really originates (this will happen a lot, so be aware of this possibility in general. Often the problem is not actually what the error message complains about! It’s only some consequence, but the real problem started elsewhere). Maybe get LaCheck for better error handling. Overleaf’s error messages are quite helpful I think.

In order to comment huge batches of text out, you might want to place them in extra documents you include in the main.tex. That way, you can comment out a lot by just commenting out one line. Or use a keyboard shortcut to make commenting out more efficient maybe (like TeXmaker for example has them to bulk comment and comment out lines).

 

Understand the code base by adding comments

In case your working with (parts of) somebody else’s code, the problem might originate from there. Or from the interaction of these old parts with the new stuff you added. Or improper use of the functionality provided. (Are you sure you understand what exactly that package is supposed to do and who to use it?) You can get a better grip of somebody else’s code by commenting it line by line, explaining to yourself what it does. Do this only if it’s not too much code, though, or it will be too much work. Maybe don’t do this for package implementations as a newbie. This might be relevant for code you just pasted in from StackOverflow without properly understanding it though.

Write it again from scratch, maybe the mistake will have mysteriously disappeared!

Sometimes, it can actually help to just write the code again from scratch if possible. I find that often, with the additional knowledge about my programming problem that I have learned during the debugging process, I don’t make the same mistake again and the code is much better for it and works. Even in some rare cases where I really couldn’t find the error. Often, just simplifying it is enough as the problem might just have been introduced by unnecessary complexity. 

I think in my case, the problem is often cluttered documents which contain lots of packages I’m not actually using (anymore). Those can either be the hidden causes of errors or they can at least obscure their origin. In those cases, starting fresh can solve the problem.

I have realized this many times when preparing a Minimal Working Example to ask a question on some help site (like TeXStackExchange or StackOverflow). Without the clutter, the code actually worked. Oops. Be sure to check for this possibility first before posting a question somewhere (on the proper etiquette for asking for help, see The most important tip for confident LaTeX newbies: Don’t reinvent the wheel! (and try a Minimal Working Example instead).

 

So, that’s it for now. I hope I could help you out.

Thanks for all the fish!

Best,

the Ninja