Find that bug! Using a search engine as a programmer

Most bugs you encounter have been encountered by others before you; most programming problems you face have been faced by others as well. And many of those people have written down details about what they’ve learned—in issue trackers, documentation, and blog posts.

All you have to do is find this information.

Typing a phrase in to your search engine of choice will sometimes take you straight to the right answer. But quite often, the results aren’t helpful.

No need to give up, though: there are still plenty of ways you can productively keep searching.

Use site-specific search too

It’s easy to believe that search engines have all the answers right at the top, but they actually hide quite a lot of content deep in their results. And some obscure content never gets indexed at all, which is unfortunate when it’s the obscure content that you need to find.

So instead of just using a search engine, use the local search engine of the project issue tracker, the documentation, StackOverflow, and so on.

For example, let’s saying you’re using Eliot, a somewhat obscure Python logging library I maintain, and you want to use it with the Pandas library. Unfortunately, you get an error, so you search Google for the text of the error: eliot dataframe is not json serializable. Now, there is an actual issue in Eliot’s GitHub issue tracker with this exact error message—but as of August 2020 Google doesn’t return it, probably because it didn’t bother to index that page.

But if you were to use the search form on the Eliot GitHub project’s issues page, you would find the issue that mentions this particular error. In this case, as in many others, the search engine isn’t actually indexing everything: you have no choice but to use the local search engine.

Local search engines often have the additional benefit of allowing more structured search, for example:

• An issue tracker might let you search by open/closed status, labels, or the affected version.
• StackOverflow questions are tagged with particular technologies by the person submitting the question.

You still want to use a search engine

A software project’s documentation and issue tracker are a great place to start searching, but sometimes you’ll find solutions elsewhere.

For example, if you have a problem with library A, it might be that project B had the same issue, and you can find a workaround in their issue tracker. Or perhaps someone wrote a handy blog post on the issue—or they might have other related content. And that related content can also be useful.

Read results that don’t answer your question

Often you’ll encounter results that solve a similar but not identical problem. Read those pages anyway.

First, because you’ll learn more about the shape of the problem, broad approaches, and how the underlying software works.

Second, because you might find suggestions of new places to search.

Third, because this will give you an opportunity to apply your close reading skills and learn more domain-specific jargon. You can then use this jargon to widen, narrow, and vary your search.

Note: This article is an excerpt from my book, The Secret Skills of Productive Programmers, which also has a chapter on close reading.

Narrow and widen your search

Let’s say you’ve tried an initial search engine search, and you got a huge swath of unrelated results. For example, if I use Google in private mode to search for eliot, I get many entries about the poet T.S. Eliot.

Given too many results, you need to focus in: add a keyword or two that will help narrow the results to those you care about. In this example, searching for eliot logging find the actual Python library; searching for eliot python also helps.

Again, the jargon you’ve found along the way will help you know what to add.

If your search is too specific, you can do the opposite, removing some unnecessary keywords.

Try lots of variations by using jargon

Even if your initial searches don’t work, you shouldn’t give up: now is the time to start using synonyms and alternative phrasings. You are using a certain phrase to describe the problem, but other people might conceptualize it a different way, and use different phrases.

If you can rephrase the search you are likely to find many results you haven’t seen before. For example, let’s say you’re using the Pandas dataframe library for Python and you’re running out of memory. If you search for pandas too much memory, pandas out of memory, pandas large files, and pandas out of core will give you some overlapping results, but each returns some results you won’t get from other phrases.

The last term comes from “out-of-core computation”, a computer science term for algorithms that process data that doesn’t fit in memory. How might you learn about that phrase? By collecting jargon as you go along.

Search for errors the right way

When searching for errors, you need to copy/paste enough that you’re identifying the specific error, but not too much such that the search engine can’t find any matching results. For example:

Traceback (most recent call last):
  File "/home/itamarst/flask/app.py", line 2446, in wsgi_app
    response = self.full_dispatch_request()
  File "/home/itamarst/flask/app.py", line 1951, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/home/itamarst/flask/app.py", line 1820, in handle_user_exception
    reraise(exc_type, exc_value, tb)
  File "/home/itamarst/flask/_compat.py", line 39, in reraise
    raise value
  File "/home/itamarst/flask/app.py", line 1949, in full_dispatch_request
    rv = self.dispatch_request()
  File "/home/itamarst/flask/app.py", line 1935, in dispatch_request
    return self.view_functions[rule.endpoint](**req.view_args)
  File "flask1.py", line 18, in index
    return _counter + "\n"
TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Different languages will have different formatting, but the basic idea is that the lines that includes directories are specific to your computer. Searching for /home/itamarst is not going to get good results!

Searching for the last line might work:

TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Or maybe the last two lines, if that line is from code I downloaded and didn’t write myself:

    return _counter + "\n"
TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Or perhaps I want to understand the generic error, rather than this particular instance:

TypeError: unsupported operand type(s) for +:

Or perhaps I think this is a problem in the Flask library rather than my code, in which case I might search for:

flask TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Typically the important information will be either at the beginning or the end of the error traceback or stacktrace.

(Thanks to Jason Swett for suggesting this technique.)

Finally, be careful

One issue with searching for random solutions on the web is that the proposed solution is sometimes wrong or broken. I’ve seen people propose insecure solutions on StackOverflow, and then get upvoted by other people who don’t know any better.

Just because the solution seems to work doesn’t mean it’s correct: you still have to think, do some additional research to validate the proposal, and probably write some tests too.

Want more ways to become a more productive programmer? This article is an excerpt from my book, The Secret Skills of Productive Programmers.