Sort of in the same vein as my last paper review post, I'd like to start periodically posting a weekly links post. In theory I should publish this every week, but I don't want to make a hard time commitment. Instead, I'm going to make a point of writing up little blurbs about things I find interesting and publishing that when I have enough. These can be things I'm reading, things I'm watching, or anything else, but the key thing is that I found them interesting in some way and perhaps they led to some change in how I'm thinking about or doing things.

Inspiration🔗

I came across Slime Mold Time Mold's blog a bit over a year ago and have been a big fan since. Based on their blog I even decided to eat essentially nothing but potatoes for a month (I probably owe you all a blog post about this experience too). This is also where I got the idea to do this style of post. Each month they post a set of links for the month, like these links from July. I enjoy the breadth of things they include in these links and usually learn something interesting in them.

Documentation🔗

At work I'm starting to do a lot more documentation work. A colleague pointed me to the idea of the Four Kinds of Documentation. That links to a recording of a talk about it, but this page covers a lot of the same material in text and pictures. But, for those you want the punchline right away, the four kinds of documentation are:

Learning-oriented tutorials
Goal-oriented how-to guides
Understanding-oriented discussions
Information-oriented reference material

That said, the talk has a lot more context about what these mean and how they relate to the talk so please don't just use my summary of it.

Error Handling🔗

Andrew Gallant had a great post this week about error handling in Rust. The core idea is to use panic! for bugs and Result for errors. There's a lot of other good advice for how to put that philosophy into practice. I found the part about whether we should lint for unwrap() and expect() interesting. On one of my side projects I recently enabled lints against both unwrap() and expect(), and I think I'm going to turn the lints off because while it did improve some of my code, in other cases it led to make basically inlining my own version of those functions. I used to be an advocate of using expect() in place of unwrap(), but I think that was before Rust had #[track_caller], which meant unwrap() could only tell you something went wrong with no other context. Nowadays I find unwrap() is often perfectly sufficient to diagnose and fix a bug.

On the subject or error handling, I'll share an older post from Joe Duffy on the error model in Midori. This has been a favorite post of mine for a few years now, as it introduced me to the idea that bugs (cases where the programmer made a mistake) and errors (cases where something went wrong that should be anticipated and handled gracefully) were different and that it was reasonable to have different mechanisms for them.