What you see vs. What's there

by David Humphrey

I spend a lot of time helping students review and debug their code. During the pandemic, it's all I do some days.  Doing as much of it as I do, I wanted to say something about the value of plain text over screenshots when asking for help with code.

I've long taught my programming students that Plain_Text > Images, and that despite being taught that "a picture is worth 1,000 words," when it comes to software development, plain text beats any screenshot: text can be indexed and searched; it is automatically cross-platform and requires no proprietary tools; text is accessible; text can be copy/pasted/imported/transformed/repurposed.

Despite all this, I find that Plain_Text > Images can be a hard truth to gasp at first.  I know because I also failed to understand it early on in my career.  Screenshots have colour, use nice fonts, and most seductively, screenshots show you what I see.

The thing is, when I'm debugging a technical problem, I'm rarely interested in what you see.  Instead, I want to know what's there.  This distinction is the difference between "it's not working" and "this is what's happening."  Most importantly, it requires a shift in focus from something not working to seeing everything that is actually taking place.  A computer not doing what you want necessarily includes you and your desires, and solving your problem often involves removing (or ignoring) both.  What is the computer doing?

When you're starting out, a 400 line error message seems overwhelming.  Since none of it makes sense to you, sharing a picture of the last few lines is as a good a starting point as any.  When I first began working on Mozilla's code I used to struggle a lot with this.  Building Firefox with make -j  would spin up a lot of parallel processes, and when one of them failed and the other 6 didn't, you'd have a huge wall of text with a tiny error buried somewhere in the middle.  I can't count the number of times I'd share failing build output and be told, "Your error is above all that, scroll up."

Figuring out what's wrong involves really seeing what's there.  You have to stop thinking about the current situation in terms of what's not happening: because it's not happening, it's not your concern.  You have to let go of your goal and replace it with a full view of what's in front of you.

With code that means considering the full text of an error message or the complete output of a program.  We've been trained to click "OK" on long Terms of Service or License Agreement dialogs, without ever reading what's there.  Errors aren't like that.  You need to be able to look through the whole thing.  You're a detective arriving at the scene of a crime, and solving it will involving finding some clues.

Like a detective's magnifying glass, a terminal is a tiny viewport into a long history of commands and output.  Figuring out what's happening so that you can adjust course usually involves searching or scanning the text of that multi-screen error message, build log, or warning text.  "Your error is above all that, scroll up."

Learn how to copy and share big blocks of text in your terminal.  If your current terminal doesn't make that easy, get a better terminal.  Discipline yourself to prefer copy/pasting text whenever you feel yourself reaching for the screenshot key-combo.

Above all, don't be afraid to read the output and errors of the programs you run and write.  This impenetrable text is really mean to provide you details you can use to track down your issue.  Some of it matters and a lot of it doesn't.  Begin by assuming it's all part of what's happening, and share it when you are asking for help.