dhwthompson.com

My favourite Git commit

2019-08-30T00:00:00+00:00

I like Git commit messages. Used well, I think they’re one of the most powerful tools available to document a codebase over its lifetime. I’d like to illustrate that by showing you my favourite ever Git commit.

This commit is from my time at the Government Digital Service, working on GOV.UK. It’s from a developer by the name of Dan Carley, and it has the rather unassuming name of “Convert template to US-ASCII to fix error”.

A quick aside: one of the benefits of coding in the open, as practised at GDS, is that it’s possible to share examples like this outside the organisation that produced them. I’m not sure who first introduced that idea to GDS – it was well-established by the time I joined – but I’m forever grateful to them.

Why I like this commit

I’ve lost count of the number of times I’ve shared this as an example of what commit messages can do. It’s fun because of the ratio of commit message to code change, but that’s not why I think it’s worth sharing.

In a different organisation, from a different developer, this entire commit message might have been change whitespace, or fix bug, or (depending on the team’s culture) some less than flattering opinions about the inventor of the non-breaking space. Instead, Dan took the time to craft a really useful commit message for the benefit of those around him. I’d like to step through a few of the ways I think this is a really good example.

It explains the reason for the change

The best commit messages I’ve seen don’t just explain what they’ve changed: they explain why. In this instance:

I introduced some tests in a feature branch to match the contents of
`/etc/nginx/router_routes.conf`. They worked fine when run with `bundle exec
rake spec` or `bundle exec rspec modules/router/spec`. But when run as
`bundle exec rake` each should block failed with:

    ArgumentError:
      invalid byte sequence in US-ASCII

Without this level of detail, we could hazard a guess that this commit fixed some kind of parsing error in some tool or other. Thanks to the commit message, we know exactly which tool it was.

This kind of information can be really valuable to document, and is all too easy to lose as people forget the original context behind their work, move on to other teams, and eventually leave the organisation.

It’s searchable

One of the first things in this commit message is the error message that inspired the change:

ArgumentError:
  invalid byte sequence in US-ASCII

Anyone else who comes across this error can search through the codebase, either by running git log --grep "invalid byte sequence" or by using GitHub’s commit search. In fact, from the looks of the search results, multiple people did so, and found out who had found this problem before, when they came across it, and what they did about it.

It tells a story

This commit message goes into a lot of detail about what the problem looked like, what the process of investigating it looked like, and what the process of fixing it looked like. For example:

I eventually found that removing the `.with_content(//)` matchers made the
errors go away. That there weren't any weird characters in the spec file. And
that it could be reproduced by requiring Puppet in the same interpreter

This is one of the areas commit messages can really shine, because they’re documenting the change itself, rather than documenting a particular file, or function, or line of code. This makes them a great place to document this kind of extra information about the journey the codebase has taken.

It makes everyone a little smarter

One thing Dan did here that I really appreciate was to document the commands he ran at each stage. This can be a great lightweight way to spread knowledge around a team. By reading this commit message, someone can learn quite a few useful tips about the Unix toolset:

they can pass an -exec argument into find to run a command against each file found
that adding a \+ onto the end of this command does something interesting (it passes many filenames into a single file command, rather than running the command once per file)
file --mime can tell them the MIME type of a file
iconv exists

The person who reviews this change can learn these things. Anyone who finds this commit later can learn these things. Over enough time and enough commits, this can become a really powerful multiplier for a team.

It builds compassion and trust

Now the tests work! One hour of my life I won't get back..

This last paragraph adds an extra bit of human context. Reading these words, it’s hard not to feel just a little bit of Dan’s frustration at having to spend an hour tracking down a sneaky bug, and satisfaction at fixing it.

Now imagine a similar message attached to a short-term hack, or a piece of prototype code that made its way into production and set down roots (as pieces of prototype code love to do). A commit message like this makes it much easier to remember that every change has a human on the other end of it, making the best decision they could given the information they had at the time.

Good commits matter

I’ll admit this is an extreme example, and I wouldn’t expect all commits (especially ones of this size) to have this level of detail. Still, I think it’s an excellent example of explaining the context behind a change, of helping others to learn, and of contributing to the team’s collective mental model of the codebase.

If you’re interested in learning a bit more about the benefits of good commit messages, and some of the tools that make it easier to structure your changes around them, I can recommend:

Telling stories through your commits by Joel Chippindale
A branch in time by Tekin Süleyman

My brain, and how to help it

2018-09-22T00:00:00+00:00

I originally published this post internally for my colleagues at Monzo (hence the emoji). It seemed useful enough there that I figured it was worth publishing on my own site. I’ve very gently edited it to remove a couple of references that don’t mean much outside the company.

Hi

My name’s David. I started at Monzo a month ago.

I’m also autistic. I got a diagnosis last July – specifically, Asperger syndrome.

I find new situations and environments stressful, especially when I need to figure out what the rules and social conventions are, or when it’s otherwise hard to anticipate what’s going to happen. So starting a new job is pretty tough. Especially somewhere as fast-paced as Monzo. Especially when I’m still figuring out what my diagnosis means and questioning my models of the world.

I’ve told a few people here at Monzo, and the question most people have asked is:

What can I do to help?

What you can do to help

⏰ Give me time

I find surprises difficult to deal with. They put me off balance, and it takes time and space for me to recover. That surprise could be a sudden change of direction, a nasty surprise in the codebase, or some critical feedback I’m not expecting. If I’m feeling stressed, it could even be a loud noise.

I’m not saying you should avoid these – most of them are unavoidable, and critical feedback in particular is incredibly valuable – but be aware that I might need more time to process them than most people.

👨‍🏫 Give me clarity

I can’t always guess how someone is feeling, how the things I say will come across, or what someone expects of me. If you expect me to do something, let me know very clearly what it is. If I’ve said something you felt was rude, definitely let me know (but please give me plenty of time to process it: see above).

👀 Give me context

My brain works in rules and systems. It’s part of what makes me good at my job. It also means I struggle if I don’t understand why I’m doing what I’m doing, or how it fits in with the wider goals of the team or the company. The more context you can give me about the thing I’m doing, how it fits together, what the background is and why it’s important, the happier and more useful I’ll be.

🗣️ Take turns talking

This is a small thing, but it makes a huge difference to me. If there are multiple people talking at once, I’ll really struggle to follow what’s going on.

AMA

Do you have more questions? Have I said something that isn’t clear? I’d love to keep talking about this. For one thing, it helps me clarify my own understanding of my brain and how it compares to everyone else’s brain. Feel free to ask me anything.

Being autistic

2018-04-02T00:00:00+00:00

On a Thursday last July, in a clinic just outside Cambridge, a psychologist sat down with me and confirmed that I have Asperger syndrome.

It wasn’t a huge surprise – after a slew of questionnaires, an extensive reference book and a year-long waiting list, I was already pretty convinced I knew what the answer was going to be. Even so, it was a big deal, and has been a big deal since, to reframe and understand the last three decades. And now here I am. Telling you.

Hi. This is me.

A very brief introduction to Asperger syndrome

Asperger syndrome is a form of autism. Like the autism spectrum itself, Asperger syndrome covers a whole range of traits, which different people are going to have to different degrees. Probably the most well-known traits are around highly specialised, very intense interests, and difficulties understanding body language and subtext. I don’t want to go into much detail here, as other people and organisations have already written far better introductions than I ever could. If you’d like to know more, the National Autistic Society has a pretty good introduction to Asperger syndrome, and some broader information about the autism spectrum as a whole.

Before I start delving into the details, I feel it’s worth making clear that this is all my own personal experience of my own personal brain, and doesn’t necessarily apply to other autistic folk. It might, but please don’t make too many assumptions. On top of that, I’m still relatively new to this, and writing as I learn, so there may well be parts I’ve misunderstood, and there are definitely parts I haven’t figured out yet.

With that said, here’s what I’ve figured out so far about how my mind works.

How my mind works

My mind’s pretty specialised. It’s very good at a number of things most people’s minds struggle with, and it struggles with a number of things most people do without even thinking.

As far as I’ve been able to figure out so far, the things my mind is best at are details and systems. It‘s part of what makes me a good programmer: I can hold a lot of detail in my head about how a system fits together, I can mess around with it more easily than most people, and I can pick up on details other people might miss, such as potential bugs. A lot of the things I enjoy (and seem to be pretty good at) are those where there’s an underlying system to figure out and master – computer games, martial arts, even cooking.

Then there’s a few things my mind struggles to handle. Most of them revolve around people.

I’m not always great at figuring out what someone else is thinking, or feeling, or even dropping hints about. I can take educated guesses, for sure, but I don’t necessarily get it right. It also takes a lot of work to keep track of all the social cues going on whenever there’s a conversation happening, and all the social conventions most people seem to follow without even thinking. I can think of several times when someone has asked me how my weekend went, and it’s completely slipped my mind that the appropriate response is to ask them about theirs too. It’s not that I don’t care; it’s that I’m having to concentrate so much on the rest of the social cues that I take longer to catch up with how the conversation is supposed to go.

All of this is usually manageable when I’m talking with one person, but add in a few more people to keep track of and I really start to struggle. Throw in some background noise, or get several of those people talking at once, and I’ve got very little chance of following what’s going on.

Another thing I’ve noticed is that surprises throw me pretty hard. While other people seem to be able to roll with surprises fairly easily, it takes me longer to recover, and I’m less able to function in the meantime. That surprise might be an unexpected change of plans, an abrupt change in a discussion topic, or even a sudden loud noise. It’s probably going to knock my brain sideways for a while, and I’m going to be that bit twitchier until I’ve recovered.

A few things don’t really count as good or bad: they’re just things my brain seems to do a bit differently. My memory seems to have some pretty strong opinions about what is and isn’t worth remembering. Movie quotes? Yup. Which actor was in which episode of which series, or voiced which character in which game? Keep it. Different types of bird or plant? Nope; unless I can eat it, it’s already forgotten.

There’s a whole load more traits I could cover here – also, I don’t doubt, a whole pile of traits I haven’t yet identified as a part of this particular pattern – but I hope that gives at least a flavour of what makes my mind a bit different from most.

What this means for me

On the surface, nothing’s really changed. I’m still exactly the same person I was before, and have always been; the way my brain is wired is the way my brain has always been wired. None of that has changed; what’s changed is that now I know about it. I can better appreciate the things I’m really good at, and I can better accept the things I struggle with.

Perhaps most importantly, I think this means I can try just a bit less to fit in with what I think other people expect of me – and what I’ve grown up expecting of myself – because all that’s going to achieve is a second-rate emulation of another person. Instead, I can accept that I’ll need to make a few adjustments when dealing with other people, and maybe ask those people to make a few adjustments in turn.

The most common question people have asked me is whether this diagnosis is a good thing. In short: yes. Yes, it is. For the technically-minded, it’s like struggling with a problem for what seems like an eternity, then finding that one abstraction – that one missing piece of the puzzle – that makes the solution fall neatly into place. Except that problem is the last three decades of your life. For the less technically-minded, it’s like finding out you’re a penguin. Either way, it’s very good indeed – nothing short of life-changing, in fact – and I’m looking forward to finding out more about what it means.