Homework 8

Reading and explaining code

Please submit homeworks via the new submission page.

Writing and debugging code isn’t the only hard part of software development. There are two other particularly challenging tasks: comprehending code and maintaining code. You may not have had a chance in other classes to explicitly practice reading and maintaining code.

HW07 gave you a chance to practice maintaining code: given your HW06, you had to remove some features and other new ones… finding, creating, and fixing bugs in the process.

In this homework, you’ll have a chance to comprehend some code: you got a handout in class, but you can download it here. I’d like you to annotate this code and explain it. You’ll submit a Literate Haskell file.

How to explain code

You’ve seen a form of “code + explanation” in the Literate Haskell homeworks you’ve done so far (HW01 through HW05). Each homework has a bunch of text around bits of code—often substantially more text than code. Such literate programming is a popular way to think critically about code.

I’d like you to go a step further than I do in the homeworks: really explain what the code above is doing. You can assume that your reader is familiar with functional programming and has used the IO monad, but none others.

In order to help you do a good job explaining, here are two examples. The first is an explanation of Clojure code for a rhyming dictionary, written by Paul Ford. His whole explanation is a in a jocular, knowing tone. I quite like his writing, but it’s very hard to emulate.

Keeping up the Clojure theme, here’s an example of literate code for an ant simulation.

Another, much more detailed example is libavl, a C library for various kinds of search trees. The entire documentation is an enormous, chaptered literate program!

These last two examples are more direct and less funny and less literary than Paul Ford’s exposition. I urge you to write in a simple, comfortable style: no need for stuffy language or programmer-ese, no need for unnecessary formality. You can use ‘I’, you can tell a story. (Notice how Paul’s explanation is also the story of him coming to understand the code. It feels like an adventure you go on together, though it turns out that he knows where to go the whole time.) If you can be funny, that’s great: programming is hard, so jokes can leaven things… but don’t overdo it and distract from the message by being silly or obtuse.

Parameters

I’d like you to annotate the code. The original code text comes to two pages in my printout; your final annotation shouldn’t be longer than six pages… but it might be less.

The ideal exposition will not only fully explain the code (what is it for, what are the instances doing, what do the examples mean, how does it all work), but come up with new code snippets to explain what I’ve written.

In any piece of writing, it’s important to know your audience. Please pretend that your reader has just finished HW05—they have an understanding of Functor, Applicative, and Monad, but no deep experience. They may not know all of the syntax that’s used in the file, so you may need to explain it.

Please be concise. Longwinded, stilted explanations are exasperating.

Revise. Try reading what you’ve written out loud, mumbling through the code parts. Keep revising text until it’s possible to read what you’ve written smoothly, without any awkward pauses or disfluencies.

Please format your final work as Literate Haskell, i.e., like the homeworks. Literate Haskell allows (most) Markdown, like underscores for italics or double asterisks for bold.