Read the Code

Woof! Road trip! Moving! The last week of the contract! Looking forward to a little bit more quiet and routine for the next couple of weeks, though, you know– still moving.

I'm shifting back into the "other" mode of #hashtag #consultant life – writing, networking, photographing, personal projects, and generally just managing my own schedule. I've managed to complicate my situation a little bit compared to last time by starting a couple of projects with friends and signing up for Small Bets. And, uh, moving. Have I mentioned moving?

Towards the end of the project, I was mobbing with Andrew Edstrom (who also has a newsletter, you should go over there and subscribe) and a client, and we were trying to figure out how to use an internal library. The README was enough to get us started but even after putting in what we thought was the right configuration, the tests that we thought should pass weren't passing.

We looked at some other tests that used this same library but their setup was pretty different from ours. We talked through a couple of possible problems there might be with what we'd implemented so far and discussed some changes we could try to see if we were right– but they were guesses, really, all variations on "try something and see if it does the right thing." (Which is a strategy I also endorse– but that's another newsletter).

Then I said, "Oh. Or. We could go read the code. That would tell us what it's going to do with the value we're passing in, and that will probably tell us what's going wrong and what we should be calling instead."

Andrew started laughing, so I asked him what was so funny, and he tells me, "Oh, that's just a very Nat suggestion."

And the surprising thing, really, was that I hadn't brought this up before that point– that we'd spent as much time as we had just working from the documentation. I want to believe that there's value in documentation– a lot of very smart people, who are better programmers than me, have written a lot about how it's important to document your code– but constitutionally I cannot bring myself to rely on it.

The code always tells the truth.