Road Trip Day 2

Attention conservation notice: This is the rarest category of post on this blog – one that’s just “Hey I’m me I did some stuff”. Specifically this is about my current road trip. If you don’t care about what I’m up to, which is really fair enough, you can skip this one.

Well, I seem to have failed to talk myself out of this road trip plan, so here I am in sunny Penzance!

OK, well, here I am in Penzance. It’s quite wet. There are very few pirates, and the WiFi is down where I’m staying so I can’t even torrent things.

The story so far:

Yesterday I drove down from home (near Cambridge) to my aunt and uncle’s place near Reading. On this trip I learned a very important lesson: If you’ve left your sunglasses in your bag and are driving into the setting sun, the correct thing to do is to stop somewhere and get them out. Toughing it out and staring into the sun for two hours as a result is stupid and will result in losing the evening to a splitting headache. Despite that I had a lovely evening catching up with family until the headache finally got the better of me.

I hadn’t actually appreciated this aspect of doing a road trip at this time of the year, but it came into play to a lesser degree this morning; the sun is perpetually very low in the sky, which means that it’s perpetually in my eyes while driving. Fortunately today I did remember my sunglasses.

Still, my inclination had already been that I’d be better off driving after it got dark, arriving at my destination and then doing the actual exploring the next day starting from around sunrise. I think this pretty much cements that as being a good idea.

I decided to take a slightly more scenic route here – when plotting my route Google maps gave me three options. Two were boring motorway driving, the other was still a lot of A roads but swung further south and went through more interesting scenery, taking a bit under an hour longer.

Google maps navigation really doesn’t like it when you do this. About every ten minutes for the first hour the navigation kept saying “We have found a faster route going the way you told us you didn’t want to go. Press accept to use that” (paraphrasing).

I’m reminded of my observation that GPS is basically Revenge of the Turtle Graphics – once we told a little turtle in a computer how to move around on a screen, now the little turtle is telling us how to move around on a map.

The turtle gets very grumpy when the humans don’t follow its advice.

The turtle might also have been right, in that a five hour drive was really a bit too much – I think that might be the longest drive I’ve done in one go (if it’s not it’s certainly close, but the longest I can think of were only about four hours). I’m not destroyed after it, but I’m definitely pretty tired, and at least some of that was from the driving (the rest of it was that going to sleep with a splitting headache that painkillers won’t shake doesn’t lead to a restful night).

This is an interesting demo of my changing relationship with driving – shortly after passing my test I did a three hour drive and ended up absolutely shattered (the plan had been to continue driving the next day. I left the car where I was and got a train the rest of the way). Back in February I did a three hour drive across Namibia mostly for fun and it was fine but A Big Deal.

These days three hours drives are just things I do sometimes because I needed to. Five hour drives are hard work but basically fine. I guess one consequence of living in the country is grinding driving.

I have decidedly mixed feelings about this. I’m still politically mostly against cars – I will dance on the grave of the internal combustion engine, I think we desperately need more and better public transit, and I think that self driving cars will be life saving and that’s enough to justify them on their own without all the other benefits – but after spending a lot of time in one I’m starting to have more appreciation for cars too.

On net, I welcome our car-free future. But I’m starting to see that something of value will be lost too. I need to think about this further.

On the driving length front though, I don’t expect that to be a problem on this trip – 5 hours is a lot more than I intend to drive most days – because I’m regarding Land’s End as the real start of the trip, I just wanted to make a beeline down here. I’ll probably be doing more like one or two hour drives most days.

I’m staying at the Penzance Youth Hostel tonight – going to see how the shared rooms go (I have earplugs and a mask). Tomorrow will do a bit of walking around the countryside around Land’s End (I spend about an hour wandering around Penzance itself when I got here and feel like I don’t need to spend more time in the town itself), then tomorrow evening I’m off to the Eden project to stay in the Youth Hostel there. I’ll get a room to myself there! With en suite and everything! This would feel more of a luxury if the room in question weren’t a shipping container. But I’m looking forward to the Eden Project itself, and the rooms are reportedly very nice despite the hipster chic construction material.

(I’m sure I’m being unfair and that using shipping containers for construction actually makes a great deal of practical sense in many contexts, but my association with them is very much Boxpart, which is basically flat-packed hipster gentrification).

That’s pretty much all I have to say for now. I doubt it made much sense given aforementioned tiredness. I’ll post further updates from time to time as I make my way around the country.

A reset protocol for my body

Epistemic status: A collection of things that seem to help based on non-calibrated trial and error on a study of N=1. Note also that I am not a doctor and this should not be considered proper medical advice.

This is a combination of things I find useful when I am feeling in a state I would describe as “generally out of sorts”. Possible incomplete symptoms of this are:

Headache
General soreness/stiffness
“Foggy head” – difficulty thinking, focusing, etc
Restless energy/jitters making it difficult to focus
Mild to moderately bad mental health day (depression, anxiety, high irritability, etc)
Fatigue

Or, as I like to call it, “It isn’t 16:00 yet” (I am only being somewhat facetious. the expected number of symptoms from the above list I experience on a given day is > 2, and they tend to be especially severe until about mid afternoon).

This is often triggered by having slept badly, but that’s somewhat definitional for me: If I wake up feeling this way then I consider myself to have slept badly even if I’ve had 8 hours of apparently solid sleep.

(Yes this is probably a sleeping disorder of some sort. No it’s probably not sleep apnea. Yes I do now have a referral to a sleep clinic).

Anyway. Regardless of the cause, with a combination of effort and tactics this is a relatively fixable state. The fix doesn’t take me to “WOO I FEEL GREAT” but it takes me to “WOO I FEEL ACCEPTABLE” more often than not, and significantly more often than regression to the mean seems to.

I cannot guarantee it will work for you, but it seems to work for me.

The Basic Protocol

400mg of ibuprofen
200mg of caffeine
300mg of theanine

I am not certain of these proportions, particularly the suitable amount of theanine (on the one hand it’s a bit low for the amount of caffeine, on the other hand it’s a bit high in absolute terms). You may wish to tinker with the quantities based on your individual sensitivities.

These drugs are both good cures for the symptoms (caffeine + theanine for alertness and fatigue, theanine for reducing jitters both in baseline and from caffeine, ibuprofen for headache and general stiffness, with caffeine having a synergistic effect which makes the ibuprofen work better).

The following are also essential parts of the basic protocol:

Drinking a large quantity of water. Somewhere in the 1-2 liters range.
Eating food. Something high in both sugar and protein works well here. I like peanut clif bars.

Dehydration and low blood sugar are both contributing factors to feeling out of sorts for me. Waking up very dehydrated is in particular very common for me, and it takes a while to recover from it.

This works relatively well on its own, but is best followed by:

The Advanced Protocol

The most effective thing on top of the above is this:

Go for a run.
Have a long shower.

“A run” needs to be intensive enough to get up a good sweat. I don’t know what about runs helps here, but I’d expect it to be some combination of endorphins and increased blood flow. I do not find that low cardio strength exercises are an adequate substitute here, but other high cardio things might (people have suggested jumping jacks to me, but I haven’t tried that). A long walk is also an improvement although less so.

The shower is at least partly because if I’ve done running adequate to enact the advanced protocol then I really need one, but I do find they also help.

The normatively correct shower for this is hot then cold then warm enough to recover from the fact that I’m now freezing. I am not good at following this because I hate cold showers and usually my actual shower is warm but not too hot (very hot showers on their own seem to exacerbate things).

After this I will usually feel OK enough that I am able to be productive unless something more serious turns out to be wrong, but there are some fall back plans:

If I still have a headache I follow up with a paracetamol + codeine mix. Paracetamol on its own is rubbish and does nothing for me (and is scary), but it has a synergistic effect with codeine that makes it a magic headache-be-gone. Paracetamol + caffeine is supposedly not a great combination for your liver, but it’s sufficiently ubiquitous that it’s probably not that bad. I don’t deliberately delay taking it after caffeine, but usually the “wait and see if the ibuprofen works” period is enough of a delay.
If it’s the evening and I haven’t had any paracetamol then sometimes having a drink fixes things.

Other things

I’m considering adding a few things to the basic protocol drug regimen:

3g of glycine. I take this before bed currently on grounds that it’s harmless and there are good studies showing it improves results for people who experience moderate sleep deprivation. There are also studies showing it improves fatigue, but it’s unclear to what degree that improvement is just because it improves sleep. Also it’s cheap and harmless.
An antihystamine and a decongestant. Anecdotally this feeling seems to be correlated with being stuffed up, but it’s unclear to what degree that’s just because I’m usually stuffed up (yes this is probably related to my sleep issues, no a steroid spray doesn’t help).
Some form of anti-anxiety med. One of the benefits of theanine is that it is a mild anti-anxiety drug, but it’s not a very powerful one. Given that a number of the symptoms of this are mood issues this seems like a thing worth investigating.

Anyway, this is just my protocol, and may not work for you, but it’s been refined enough over the years and continues to be modified over time that I figured there might be some useful knowledge for other people in it. I hope some of it is helpful.

Similarly, I imagine other techniques will work for other people, and maybe there are some that work for me that I don’t know about! Please feel free to use the comments section to share suggestions (or let me know elsewhere and/or privately if you prefer)

I like short books

(and I cannot lie)

I made a comment on Twitter the other day that short books, especially textbooks, tend to be atypically good – it requires skill and focus to condense an idea down into a compact text, and you often end up with a much better work as a result of it. As a bonus, you can often read through them over the course of an afternoon which lowers the cost of rereading significantly.

People asked me for some recommendations based on this observation, so I had a rummage through my shelves…

…and ended up actually much less convinced of my thesis than I started out. A lot of the shorter books seem to be ones I never finished or only half remember the contents of.

Another thing I realised is that my impression of what counts as “short” is very much influenced by printing – some books have thinner paper than others, some have larger pages, etc. and the result is that books that are within 50% of each other in terms of page count can look be radically different in size.

Despite those caveats, some of the books I dug up are still pretty good, so here’s a sampling of short books from my shelves that I’d recommend.

Best Kept Secrets of Peer Code Review

This was the book I was reading that prompted the observation. I reviewed it the other day. Nice, short book about some of the research on code review effectiveness.

Totals 164 pages, of which you’ll probably want to skip about 35 due to them being outdated.

Probability with Martingales

Martingales are essentially a mathematical model of gambling (and other gambling like things like literally all of finance). It seems to be named over the classic betting model of doubling your bet every time you lose, and is the theory you need if you want to understand why that’s more or less the only way to beat the house and if you have a finite amount of wealth then you can’t.

The book starts with a good introduction to probability and measure theory, then moves on to the theory of martingales. It’s reasonably comprehensive for the narrow area it covers, but takes quite a direct path through it. It’s generally well organised and well written, with just enough of the author’s voice coming through that it’s much less dry than many textbooks.

I really like this book. I don’t really know what level you need to read it – I had already covered about 30-40% of its contents in my degree before I read it – but it does require some level of mathematical sophistication.

Totals 251 pages, of which the main content comes to 191, of which the first 92 are mostly about probability and measure theory.

Finite Markov Chains and Algorithmic Applications

Confession: Despite this being one of the shorter books on the list, I’ve only actually read about half of it. I really enjoyed that half though.

I got this book because I wanted to learn more about Markov Chain Monte Carlo methods. I succeeded at that, and found its explanation of them to be fairly lucid and easy to follow. It also has some good sections on statistical counting

Unfortunately I then never used that knowledge so it dropped out of cache and I no longer really understand how they work. But if I need to I would definitely pick this book up again, only this time I’d do it while writing code to implement the algorithms in question.

Totals 114 pages, but they’re quite dense pages so it’s not fast reading.

How to Improve Your Foreign Language IMMEDIATELY

Finding this book reminded me that I should reread this book, despite the fact that I’m not currently actively working on any foreign languages.

As far as titles go, this is probably even worse than “Best Kept Secrets of Peer Code Review”. I guess you can’t judge a book by it’s cover? I wonder why nobody ever told me that.

This is basically a book about how to talk to people when talking to people is hard and you lack confidence. This is particularly valuable when you’re trying to talk to people in a language you don’t speak very well, but it’s also a more broadly applicable skill,

Totals 111 pages.

Combinatorics: Set Systems, Hypergraphs, Families of Vectors, and Combinatorial Probability

I really like this book but unfortunately turned out to really not care about most of its subject matter. If I needed to care about something it covered I would definitely read that chapter and do the exercises.

It did introduce me to Hall’s theorem, for which I am very grateful.

Totals 177 pages.

Foundations of Rational Choice Under Risk

This is basically a series of essays poking at the boundaries of subjective expected utility and seeing where it breaks.

I think I’ve read this book three times now, and enjoyed it every time, but I still can’t remember exactly which information I got from here and which information I got from elsewhere. Still, it was essential in fuelling some of my weirder opinions about decision theory.

Totals 161 pages.

Epistemology and the Psychology of Human Judgment

I actually don’t own a physical copy of this book, only a kindle edition, but the previous book reminded me of this one and I realised that I should really fix that, so I’ve now ordered a used copy.

I am barely trolling at all when I say that this epistemology textbook should be considered required reading for people who conduct interviews.

It’s all a bit epistemology inside baseball, but it contains a lot of good information from the heuristics and biases program as seen through the eyes of epistemologists, which is a useful thing for almost everyone who regularly has to make decisions (PS. That’s everyone).

I think this totals 204 pages, but I got that information from Google books.

Essays on The Theory of Numbers

A reprint of a number of papers by Richard Dedekind about the construction of the real numbers. This is (within epsilon of) my favourite construction of the reals, but you almost never see it in an undergrad course (cauchy sequences are more popular for some ungodly reason), and this is a nice, clear presentation of them.

Totals 115 pages.

A Short Course on Banach Space Theory

This is a really good book by a really good author which I sadly bought after my interest in the subject had waned somewhat. As a result I probably haven’t read more than a third of it, but I think I’d like to. I may revisit it as a result of writing this post.

I suspect it might make good companion reading to “Probability with Martingales” because it covers a lot more of the more general functional analysis and geometry that you get with \(L^p\) spaces, much of which comes from and is touched on things that are covered in the former book.

Totals 184 pages.

Mathematical Methods in the Theory of Queuing

This is a really good introduction to queuing theory that I have read cover to cover and completely forgotten the contents of because I don’t really use queuing theory on any sort of regular basis. I should reread it and see if I can figure out how to make the contents stick, because this seems like a thing I’d actually like to keep in my head.

This was one of the books I had in mind when I made the claim that short books were really good.

Totals 120 pages.

Large-Scale Inference

This is a good book about empirical Bayesian methods, false positive control, etc.

Unfortunately I’ve only read about a third of it. I started reading it when I was in my “I should learn more statistics” that resulted in my getting distracted and writing Hypothesis instead. I found the bits that I did read to be very helpful explanations of things that I still don’t entirely understand.

I guess I should reread this one too.

Totals 263 pages, so it’s heading into the territory of being a bit too large for this list.

Counterexamples in Topology

AKA “A gallery of stupid shit you can do when constructing topological spaces” or “Murphy’s guide to topological spaces”

I really enjoy topology, but this book is a nice guide to why topological spaces are not quite as intuitive as you might expect them to be if you mostly use topology to provide nicer proofs while working primarily in metric spaces. It’s got lots of weird and wonderful examples of connections you’d expect to be true but aren’t.

Unlike most of the rest of the books on this list, this one is really not for reading cover to cover and is more of a reference book, because each example only takes a page or two.

Also in the category of subjects in which my interest has waned, but if you like this subject I can recommend this book.

Totals 244 pages.

To Mock A Mockingbird

A collection of neat logic puzzles wrapped in slightly contrived stories. I enjoyed it, but other people seem to enjoy it much more than I do. I’ve always liked logic puzzles slightly less than I would expect to and much less than other people would expect me to.

Still, it’s undeniably a good book which many people really enjoy.

Totals 243 pages.

Conclusion

It turns out that I have far fewer really short books than I thought, but I still feel like I believe the thesis that (non-fiction) books whose size is in the region of 100 pages are often very good. It seems like as you approach or exceed the region of 200 pages (which is where most of these books lie) this property weakens significantly and you have enough space that they just become slightly shorter “normal length” books.

These still have the potential to be very good (and I’ve picked up a bunch of the ones listed to reread. Argh/yay), but that doesn’t feel like it’s true for any particularly interesting reasons other than that I’ve bought good books because they were good.

So I guess I’m seeking recommendations. Can you suggest good non-fiction books that total somewhere in the region of less than 150 pages?

Dividend paying sovereign wealth funds and decoupling effects

Epistemic status: Politics and economics are very far from being my area of expertise, and even to the extent that I understand them I suspect this post to be an over simplification. I think it contains the core of a good idea, but I have little to no hope of it being politically feasible.

I’ve been thinking a bunch about sovereign wealth funds recently (for values of recently that go back about three months).

The core idea of a sovereign wealth fund is that you create a state owned investment fund and fill it with tax money. Often (Usually? Always?) they are required to only invest in things outside the country,

Normally the sovereign wealth fund seems to just sit there as basically a war chest for emergencies. It was considered big news when Norway actually spent some money from their sovereign wealth fund earlier this year.

I’ve been thinking about a different use case though, which is that of the dividend paying sovereign wealth fund – one where every resident of the country receives a monthly payment out of the fund. This isn’t without precedent – the Alaska Permanent Fund more or less works like this (it pays annually rather than monthly. I’m not wed to it being monthly but I think it’s a better idea for the benefit of poorer people with less reliable income sources).

Obviously doing this significantly reduces the existing benefits of the sovereign wealth fund – if you’re spending money from it on an ongoing basis then there will be less money in it for emergencies – but I think the benefit of paying everyone a monthly dividend significantly outweighs that.

The primary reason I’ve been thinking about this is as a transitional demand towards universal basic income. Over time as the size of the wealth fund increases (due to a mix of interest, a long history of paying in and possibly/probably increased taxation) the size of the dividends will go up and the monthly payment might start to look a lot like a basic income.

This might even remove the need for a defined universal income altogether, but I’m less sure of that – a friend made the valid point that it’s a significantly less rights based approach, which has its downsides. On the other hand I suspect you’re much more easily able to argue for the rights based approach when you’re already effectively paying it out.

But I’ve been thinking about another possible benefit of the sovereign wealth fund, which is that with an additional bit of legislation it could potentially be used to smooth out some aspects of politics a lot.

The prompting thought for this is this Vox article about a carbon tax initiative opposed by the left. I don’t know to what extend the article is true, but it certainly sounds plausible: Essentially the initiative is being opposed because it is revenue neutral (it slashes an existing highly regressive tax and replaces it with a carbon tax) rather than putting the extra money into more progressive policies.

Based purely on this oversimplified description, I’m reasonably strongly on the side of the initiative, and probably would be even if my politics didn’t include a “Carbon Tax By Any Means Necessary” clause.

But in general this sort of coupling seems guaranteed to lead to a political deadlock: If you attach all your politics to all your other politics in an inseparable way, then you will be opposed by people who disagree with any of your politics. If you can decouple those somewhat then you potentially have the opportunity to find common ground that benefits everyone.

(In practice what seems to happen instead is some combination of horse trading and producing incredibly complicated bills that contain things that have nothing to do with each other as a way of striking compromises. This seems less than optimal to me, but maybe it’s secretly optimal in some way that totally makes sense if you’re a politics expert)

It occurred to me though that dividend paying sovereign wealth funds create an interesting way of achieving that decoupling.

What if you instituted a rule that any bill that gets passed must have at most one of the following three things:

A change to the dividend rate of the sovereign wealth fund
Changes (any combination of increases and decreases) to the tax that goes in to the sovereign wealth fund
Additional expenditure that comes out of the dividends for the sovereign wealth fund

No additional expenditures or revenue sources that do not go via the sovereign wealth fund are now permitted.

The result is that all coupling between taxation and expenditure now goes through the sovereign wealth fund – they’re not decoupled per se, because they’re somewhat intrinsically coupled by constraints on government revenue – but their coupling is inherently buffered and reduced.

I think doing it this way has a number of significant advantages beyond that decoupling:

Almost all increases of taxation are now significantly more progressive, and unless they would have already been incredibly regressive (e.g. taxes on public transportation, tax increases on small homes, etc) are actively progressive: Consumption is pretty correlated with wealth, so most tax increases on sale of goods will benefit the poor more. So e.g. a carbon tax is now automatically highly progressive because it just goes out to everyone and poorer people will gain more than they spend out of it.
Increases in taxation should become more politically acceptable because they will generally result in you getting some or most of the money back – the richer you are the less acceptable this will be because the numbers won’t work in your favour, but it will still be more acceptable. Additionally because they won’t be coupled to increases in expenditure, they’ll be more appealing to the small government folks.
Increases in expenditure now have a very simple and direct point of comparison: Is the benefit of this program greater than just giving people the money? I suspect in many cases this will decrease expenditure (if you don’t count dividend payouts as part of expenditure, which is arguable), but I also think that’s OK – it will only decrease expenditure in cases where people are significantly benefiting from the extra cash.
Increases in expenditure may become more politically acceptable because they are not tied to increases in taxation (although they are tied to decreases in your dividend, which may be only slightly more acceptable, or possibly even less acceptable).

There are a whole bunch of complications that I’m completely glossing over – what counts as a new expenditure vs a change to expenditure, what do you do about changes that don’t currently require legislation, how does government debt fit into this, etc. Those would all have to be solved in order to implement something like this in practice, but I expect there are reasonable solutions.

What I suspect to be the real problem with implementing something like this is that people on the left will describe it as a libertarian power fantasy and people on the right will describe it as literally communism. It seems to be almost perfectly designed to be politically unacceptable to both sides as a mechanism for giving both sides a common ground.

But I still think it might be a good idea.

Review of a book that reviews (code) reviewing

In an earlier version of my recent software development advice post, I said the following:

I also think this will not significantly reduce the number of bugs in your software. Code review is just not a cost effective bug finding tool compared to almost anything else.

I appear to be wrong in this claim, if the literature is to be believed. I don’t have a strong reason to doubt the literature, and on examination I’m not actually certain why I believed the contrary (it appears to be cached knowledge), so I’m going to change my opinion on this: Code review is probably a very cost effective way of finding bugs if you do it well, and may be reasonable at it even if you do it badly.

The thing that’s updated my opinion on the subject is reading “Best Kept Secrets of Peer Code Review“, after Richard Barrell sent me a link to a chapter from the middle of it reviewing the literature.

With a couple caveats (the title being terrible definitely counted amongst them), the book is pretty good. There are two chapters worth skipping, but that’s more a function of the fact that the book is from 2006 than anything else (GitHub’s pull requests, while far from a stellar code review system, are in all ways better than what was widely available back in 2006 and for the common path probably not much worse than the state of the art).

The authors clearly have an agenda and the book is there to promote that, but that’s OK. I have an agenda too – it’s very hard to have expertise without also having an agenda in support of that expertise. And even if I believe they’re overstating the case, the case they present is reasonably convincing. It’s also refreshingly empirical – most software engineering advice is full of anecdotes and opinions and, while this book absolutely contains some of those, it’s also got a really pleasant amount of actual research backed by actual data. The data is often not of amazing quality in that many of the studies are quite small scale so the statistics are likely under powered, but that’s still a better standard of evidence than I’m used to.

It’s also pleasantly short. The whole book is only around 160 pages, and I read it over the course of an afternoon.

Anyway, that’s the review section of this post done. Now it’s time for the review section.

I have a couple take homes from this book which are currently in the state of “Plausible sounding statements that I will think about further and probably upgrade most of to actual beliefs”.

Code review is a very cost effective way of finding defects compared to manual QA of the application – it both has a higher rate of finding them per unit of time and also finds bugs that QA were probably never going to find.
As your notion of “defect” broadens to include things like your coworkers having no idea what you wrote down, the above statement becomes stronger.
Code review should be done by individuals (possibly multiple individuals working in parallel) rather than teams working together. As well as being more expensive per unit time, team code review seems to be less effective in absolute terms at finding defects.
The generally believed opinion that a 10 line change gets more useful review than a 500 line change seems to be actually true but too generous – the actual cut off seems to be more like 200 lines. It’s unclear to me whether this means 200 lines added or a 200 line diff, but I believe it means the former.
Code review effectiveness drops off dramatically as the time taken approaches about an hour. It’s unclear to me if you can fix this by walking away from the review and coming back later. This may also be the origin of the 200 lines limit – it may be impossible for most people to effectively review code at a rate much higher than 200 lines / hour.
Code review benefits greatly from a careful first reading of code before you do any reviewing (and doing this stage more slowly is better. Presumably this hits diminishing returns at some point).
Code review benefits greatly from being structured with checklists.

The checklist one is interesting, and I am actually pretty convinced by it: The overall literature on checklists helping construct reliable processes seems to be reasonably convincing (but my opinion here is very trend driven and I have not actually read any primary research on this subject. It conforms to my biases about the world though, and thus must be true), and the specific data presented in favour of checklists for reviewing is moderately convincing. This is the advice that is the most likely to make an actual practical difference to how I review code in future.

The advice on checklists is interesting in particular in how it’s constructed: They strongly recommend not having just a “standard” checklist, but actively curating one over time: When something is found in review that seems like it would make a good check list item, add it to the list! When an item hasn’t found anything useful in review in a while (say 6 months), think about removing it.

Here are a couple example check list items from the book that look generally useful to me (the example list this is from is much longer):

Documentation: All subroutines are commented in clear language
Documentation: Describe what happens with corner-case input.
Testing: Unit tests are added for new code paths or behaviours.
Testing: Unit tests cover errors and invalid parameters.
Testing: Don’t write new code that is already implemented in an existing, tested API.
Error handling: Invalid parameter values are handled properly early in the subroutine.

There are plenty more. The book suggests that checklists should really only have about the top 10-20 items that you’ve found most useful over time (the sample checklist has 25 items, so apparently they didn’t test the invalid input case here).

One interesting thing worth highlighting is that at least some checklist items may be worth automating out of the review entirely. e.g. “Testing: Unit tests are added for new code paths or behaviours” would mostly be better handled by enforcing a code coverage metric I think.

As well as improving the quality of the review itself, the book highlights another interesting application of checklists: It doesn’t have to just be the reviewer who goes over them! Doing a sort of self review by following the checklist yourself before submitting seems to be nearly as effective at removing bugs as the review itself would be (it is unclear to me if that remains true if you skip the review altogether – my feeling is that people are likely to get sloppy at the checklist if they imagine someone is not going to be checking it later). This presumably speeds up the review process a lot by reducing the number of back and forth exchanges required to pass it.

One suggestion off the back of this self review that they made (which seems to come from the Personal Software Process world) is that as well as maintaining a global checklist for reviews it might be worth maintaining individual checklists for reviews, where people maintain their own list of things that it’s worth them pre-checking because they often make a mistake in that area which then comes up in review.

Anyway, I’m really glad I read the book. I can’t swear to its correctness, but it’s an interesting and plausible perspective that I’ll be thinking about further.

PS. If you’d like to fuel my book habit, I have a public Amazon wishlist. I’ll happily review any books you buy me…