Syntax Error #1: Welcome

Welcome!

Hello there friend! I'm really glad you found your way to Syntax Error, a newsletter about debugging software.

I started this newsletter to help software developers to turn a stressful debugging situation into a joyful exploration. You get to put on your Sherlock Holmes hat and use your deduction skills to find and fix the issues.

Each month, I'll share a technique or process that I have learned that's helpful when debugging, look at different ways different programming languages show errors and share experiences from other developers.

This first issue of Syntax Error helps you get started and in the following months we'll continue our journey and dig deeper!

Debugging mindset

Debugging can be stressful

A lot of developers aren't exactly happy when they run into a situation where debugging is needed. It is often a stressful situation and for multiple reasons: you could be facing a tight deadline; there could be external pressure from users, clients, teammates, product owners or managers; or internal pressure from thinking "am I not good enough if I can't figure this out quick". Or maybe it's Friday afternoon and you notice something was pushed to production and things broke. Been there, done that, got a t-shirt.

When we are in a stressful situation, we are in a fight-or-flight situation. Our body focuses on survival and thinking clearly and making smart moves is often not part of that. That's why I've been sharing my experience about debugging in meetups and conferences to fellow developers. There are a lot of ways we can "remove" ourselves from the situation and approach it with a clear mind.

That's what this newsletter is all about.

My secret sauce

I decided to give out my secret right away in the first email.

Whenever you are debugging, don't try to read your code and find the issue like that.

Software is very complex and trying to understand a faulty piece of code by simply reading the code will lead to time being wasted and likely you not finding out the issue. Instead, follow the steps, methods and techniques that I'll share in these emails and you'll be debugging any code, even for languages and code bases you're not so familiar with, in no time.

First thing to do: STOP!

When you are in that situation that debugging is needed, the first and most important thing to do at the beginning is to stop. Unless you're dealing with life support systems or debugging a flying plane or space shuttle, it's very likely that nobody is going to die as the result of taking your time to assess the situation.

So stop, take a breather and maybe walk to the coffee machine, water cooler or fridge and give yourself a moment to stabilize your racing mind and get out of the fight-or-flight response.

Rushing only leads to more bugs and issues down the line so that's the thing we want to avoid.

Next, reproduce the issue

First step in fixing anything is to make sure you can reliably reproduce the issue, preferably in your local environment. Otherwise, how would you ever know if you managed to fix it or not.

Once you know the circumstances when it happens, the next step is to find the right part of the code. Before you make any attempt to change the code to fix it - even if you are 100% sure* what the problem is - add something to that part of the code that confirms that it gets run. It could be a print statement, logging or triggering a debugger breakpoint.

I've seen so many cases (and made the mistake myself many times over) where a developer thinks they know what the problem is, makes changes but can't seem to fix – only to later find out that the part of the code they were tinkering with, wasn't even being run.

In future months, we'll look at some of these things more in depth and discuss different ways to do it.

Julia Evans, the creator of amazing WizardZines.com made a lovely zine of debugging manifesto.

* Being 100% sure is often a telltale sign that it's not what you think it is.

Stack trace of the Month

For the first ever Stack trace of the Month, it's only fitting that we start with SyntaxError, and this time we look at a few ways how syntax errors can occur in Python and how to solve those cases.

Helpful SyntaxError output in Python

Sometimes Python's SyntaxError comes with very helpful instructions. Like in this first example where a print clause is missing parenthesis in Python 3.x.

File "printerror.py", line 1
        print 'Hello'
                    ^
    SyntaxError: Missing parentheses in call to 'print'

Python changed its print statement from a keyword to function in Python 3.0 so this is one of the most common ways your code can trip up if you try to run Python 2 code with Python 3.

To fix this one, you'll need to add parenthesis around the content to make it a function call:

print('Hello')

A generic SyntaxError output in Python

On other occasions, the error messages are less clear.

For example, let's take a look at this code:

try:
  age = int(user_inputted_age)
print(user_inputted_age)

If we run it, we get

File "syntaxerror.py", line 3
      print(user_inputted_age)
          ^
  SyntaxError: invalid syntax

It's hard to notice where the SyntaxError is since everything in that output is perfectly valid Python (for both Python 2.x and Python 3.x).

The issue here is, that in Python, you cannot have a try block without a matching except block and it raises the SyntaxError on the first line it encounters that is missing the except.

To solve this particular one, we need to add the exception handling:

try:
  age = int(user_inputted_age)
except ValueError:
  Raise Exception('Age must be an integer')

print(user_inputted_age)

When we look at that code in this contrived example, it's easier to spot. But if you just see that SyntaxError in the wild, it's much harder to spot, especially when it happens with a less commonly known cases. These are also really hard to search for solutions online as there's nothing in the stack trace itself that is wrong.

My advice for cases where the line in stack trace looks fine on its own is to look around, especially few lines above.

Learn more

You can read more about Python's SyntaxError from my Humane Guide to Python Errors with more examples or check out Python's documentation.

Story time

If you have debugging stories or examples you want to share to the Syntax Error community, please reach out via hello@syntaxerror.tech and we might share your story!

One of my own favorite debugging stories is from years back. It's a story about making assumptions and being too eager to jump into the code before making sure what the real issue is.

I was doing support for a SaaS product and a user reached out through our support portal. They reported an issue where on a dashboard a metric showed a negative number despite the metric being such that only numbers between 0 and 1 were valid – a ratio of sorts.

These things happen with software development sometimes. Maybe there's some complicated math where a very rare corner case causes the number to become negative and no guards to check if that happens. So I dove into the code while continuing to chat with the user.

But the code looked really good and I couldn't find a way to reproduce it on my side, so I asked them for a screenshot. They took a screenshot and after a short delay, they replied that they were confused because the minus sign wasn't visible in the screenshot even though it was there on the screen.

The outcome? After that, it turned out that the user had a perfectly aligned piece of dirt or smudge on their screen that made it look like a minus sign. We had a good laugh together with them and carried on, with no bug reports needed this time.

Syntax Error is created with love by Juhis. If you liked it, why not share it with a friend? Or if you have any feedback or just want to say hi, hit reply. I'm always happy to hear from my readers and learn about what you do and how you debug your issues.

PS. I published this first newsletter issue on my 35th birthday so I'm happy you joined my newsletter birthday party 🎉