First draft materials for debugging workshop #75
Conversation
These materials are being prepared for an "Introduction to Debugging" workshop at the Spectrum Annual Meeting 2024 (23-25 September), as proposed in our August 2024 meeting.
|
|
@EamonConway @jomonman537 please see the online previous. |
|
In particular, I hope the debugger demo achieves a good balance between simplicity and showing what a debugger can do. This is followed by two examples for participants to try themselves:
The Techniques and tools page is currently incomplete, and may or may not belong in the workshop itself. It's intended as an opportunity to step back and look at the bigger picture of writing code that's easier to debug, learning debugging skills, etc — many of which are summarised in the manifesto poster at the start of the materials. I'll share this draft with the participants at our August meeting for feedback, and see if anyone has code examples they can contribute for others to explore and debug. |
|
@EamonConway I'm particularly pleased with the debugger session recording at the bottom of this page — I've written a tool for scripting these terminal sessions, which can also add chapter markers and comments. |
This page now begins with a short list of key concepts for using a debugger, and has a short introduction paragraph before the debugger session recordings (where we direct participants to use editors that support running a debugger from within the editor itself).
I wrote this tool to generate the scripted debugger session recordings.
| > You can run function 1 tests and get good answers, and then run function 2 test and get good answers, but this is because they are not sharing the state of the mutable variable. | ||
| > Sounds like a great inclusion as a mini chapter. | ||
|
|
||
| These are great ideas! The one drawback of the mutable data example is that it won't work in R, because it's copy-on-write. But that's no big deal. In fact, now that I think about, this difference us surely worth highlighting! People who are familiar with only one of these two languages need to be aware of this important difference if they begin using the other language. |
There was a problem hiding this comment.
This is great. I think it will shock some people to realise that their two favourite languages have drastic different behaviour.
There was a problem hiding this comment.
Awesome, thanks! I'm not sure how much (if any) of the "Commentary" box I should leave in the published materials ... perhaps I should collect explanations for the two exercises in a separate page at the end?
|
|
||
| ## Searching for the root cause | ||
|
|
||
| Print statements, debuggers, REPLs, last good version, recent changes, assert statements, comment out code ... |
There was a problem hiding this comment.
What do we think of highlighting the "debuggers" in bold capitals to drive home that this is what you should use (the others are okay and help, but im straight to debuggers)
There was a problem hiding this comment.
This page was a brain dump, and definitely needs to be edited/revised. Yes, I want to drive home the point that debuggers are the most direct means for observing what the code is actually doing, as opposed to what you think it's doing
|
|
||
| ## After it's fixed | ||
|
|
||
| Test cases, defensive programming, shorten the feedback loop, what coding practices might make such a mistake easier to find next time (e.g., small functions, frequent commits). |
There was a problem hiding this comment.
I agree about test cases for after its fixed, but should we also suggest test cases for when its found?
I personally think of tests that make sure the bug is reproduced before fixing code, then when I have fixed it, I have a suite of tests that should pass by ensuring the bad state is not hit. That way if it sneaks back in (which it has in the past) I catch it.
There was a problem hiding this comment.
I agree in principle, my only reservation is whether this would require a reasonably detailed treatment of writing (and running) test cases, and whether that's feasible to cover within the same workshop. But hey, maybe an example of test cases for the Python vs R example would be good, in that they'd be more than a toy example?
|
|
||
| Is the error reproducible, or does it come and go? | ||
|
|
||
| Write a failing test? |
There was a problem hiding this comment.
Oh we suggest the failing test here! I think adding it again at the point of my previous comment is also good.
There was a problem hiding this comment.
Hi,
I've left some comments for this, it is looking great.
One thing I noticed about this is that we are using the command line (which i do), but it might cause confusion for some.
Should we have an example using say Rstudio?
This will not be general, but might highlight that there are programs that make it easier for those that arent sitting around with terminal open every day.
I'm using terminal examples because they're simple to script and record, and people can copy the text at any point. I don't want to record videos for graphical editors (RStudio, PyCharm, Spyder, VS Code, etc) but I do want to show live demos using one or more of those editors in the workshop. I haven't indicated this in the materials yet, except for a tip ("Interactive debugging sessions") in the Stepping through code section. |
We now present the example (square numbers) on the next page, followed by the two example exercises. Solutions to these exercises have been added at the end of the workshop.
|
I've separated the explanation of what a debugger does (Using a debugger) from the first example (Square numbers), and added solutions to the subsequent exercises at the end of the content. I still need to flesh out and revise Techniques and tools. I'm tempted to rename this to something else, to indicate that this is about stepping back, taking stock of what we've covered, and thinking about what else you should consider when approaching debugging in your own projects. But what should we call it? Some of the titles I've considered (none of which I'm thrilled with) include "Where to from here?", "Learning by doing", "Building your skills", and "The bigger picture". Maybe you have better suggestions? |
|
For now I've called it Building your skills and made some revisions, still needs a little more work. |
The reader must now expand each solution to see the details.
This includes examples of reading strack traces produced by example Python and R scripts.
|
I've added a page about Understanding error messages where we can explain how to read stack traces, using simple Python and R scripts as examples. I think it's ready to share with our CoP, what do you think @EamonConway @jomonman537 ? |
These cannot be accessed without UNSW credentials.
Also add support for light and dark terminal themes, and use the Tomorrow Day and Tomorrow Night colour palettes, respectively.
From the meeting we had yesterday: It would be good to elaborate ever so slightly on the stack trace. We do not want to explain what the stack is, but it would be good to know that it is just popping information about the error off a queue. That way, when you are erroring within a library function (where you may not know whats happening) you can realise that you just keep going back up the stack trace until you see a function you recognise and call your self. This indicates where the error should be. |
| @@ -0,0 +1,12 @@ | |||
| # Debugging manifesto | |||
|
|
|||
| <figure markdown="span"> | |||
There was a problem hiding this comment.
We could consider listing a few errors that we have found ourselves around here?
Something that springs to mind is an "error" someone came to me with in a library, but in reality they didnt read the documentation and they thought an error code of 1 was good.
@EamonConway I've added an example of a long stack trace, what do you think? |
|
For the workshop next week, I'm tempted to leave the square numbers exercise as something that participants can choose to do, but not go through it myself. Instead, I've added a pause in the previous page for participants to try setting breakpoints and stepping through code with an even simpler example. |
|
Nobody has submitted a more detailed code example for us to work through, and I'm having difficulty coming up with a good example off the top of my head — the best I can think of is a reasonably simple SIR-type model with a typo that, e.g., negates one of the rates. |
|
Also noting that we need to merge this PR by the end of the week, so that the materials are available to participants — I will have very limited capacity (if any) to work on this next week, since we'll all be at the meeting. |
|
I've added two real-world stories of using debuggers to find and fix problems quickly: the first is an example of my own work from two days ago (Python), the other is a recent example from Michael Lydeamore (R). Check them out! |
I think this demonstrates the point. I think if we go too far on making the stack trace long it might be too impossible to decode. |
|
FYI, I'm planning to merge this by 12pm tomorrow (Friday), so please let me know if you have any final comments or feedback! |
|
This is looking really good. Ive just read through it all and it will make a great workshop |
|
I've added a final page to thank everyone who contributed to these materials, participated in the practice run, and/or provided feedback. |
These materials are being prepared for an "Introduction to Debugging" workshop at the Spectrum Annual Meeting 2024 (23-25 September), as proposed in our August 2024 meeting.
See the discussion in our August 2024 meeting for further background.