9 How to Ask Questions (and Report Bugs)

Sometime during the semester you will want to ask us questions about code. You might even think you’ve found a problem with a system being used in this course, and be inclined to submit a bug report. If you think you’ve found a problem, please do submit a report: you’re doing us a favor, and we’re grateful for it. However, before you do, please submit a good bug report.

We’ll write the rest of this document in terms of bug reporting, but the same principles apply even to asking a question.

What follows below is general advice, not just for this course but for any system you might want to write a report about, ever. It’s written in terms that make sense for programming tools, but you can generalize them to other systems without much trouble.

Any bug report should:
  • contain a full program that the recipient can run (note that code.pyret.org has a “Share” feature that creates a permanent link to a version of a program, so you can share that version even as you continue to edit your work)

  • contain a copy of the seen output (text is fine, an image if essential)

  • describe the expected output (be as precise as you can)

A developer usually initially looks at the first two parts. More times than you might think, the seen output is actually correct. Then the developer knows that the problem is to educate you on why the system is behaving correctly, and your statement of why you thought it should do something else helps them understand your misunderstanding.

If, however, the developer agrees that the seen output is not correct, now they have a problem to diagnose. Again, they will use all three parts. The first lets the developer try to get into the same state you’re in. The second lets the developer confirm that they’re in the same state. The third lets them understand what you think is wrong with this state.

In addition, a good bug report also:
  • minimizes the program and its inputs (sometimes called an MWE)

That is, you ought to send the smallest program and inputs that still demonstrate the error.

Yes, doing this last step is onerous. It’s tempting to make it someone else’s problem. But the more you make it someone else’s problem, the longer it will take them to respond. Indeed, you should assume an exponential law: for every extra line of code, it may take twice as long to get a response. That’s because your program, which is completely obvious to you, may take quite a while for your recipient to take into their heads and process. They don’t know what’s essential and what’s incidental.

So, before you submit the report, pare down. In fact, ideally, start from the empty buffer and add only what is absolutely necessary to manifest the error. As a bonus (to both the recipient and you), as you do this, sometimes you’ll find that the actual problem was a bug in your code, not in the system that you’re trying to report.

For Pyret, you can report bugs directly, though you may want to check whether a similar issue has already been filed. Beware that any code you submit will be publicly visible.