Notes at the Halfway Point

(This is copied from the first part of last week’s weekly report. I’ve copied it here since more people may be interested in what it feels like to work in a highly visible open source project.)

I’m halfway through a 3 month contract (a relationship with the WikiMedia Foundation that I hope to continue) and it seems like a good place to write up some of my lessons learned. Too many times I haven’t spent enough time going over my code. Or, when I’m refactoring someone else’s code, I don’t look over it enough. Sometimes this is due to my own inexperience with the MW code base: If I had more experience, I would have a better idea from just looking at the code that dieUsage() was being used incorrectly. Still, experience can be created, and when it is experience you lack, the effort to create experience must be made. This is where testing comes in. More than once while refactoring the UploadChunks api, Tim has just looked at the code and told me I wasn’t testing it properly. The same could be said for more trivial things like whitespace. Mixing whitespace commits with more substantive changes as well as just the way Emacs formats the code by default have irritated other developers. From this experience, I think I need to borrow an idea from Atul_Gawande’s Checklist Manifesto and make — gasp — a checklist. The checklist is the first step, but the second would be automating as much of the checklist as possible and creating a pre-commit hook that I could use to check my own code. From my experience, here are some ideas for a checklist:

  • Whitespace use.
    • Tabs, not spaces
    • avoiding spaces for indention and lining up code
    • spaces around parens
    • etc.
  • Code correctness.
    • Ensure each exit point has a test. (Since I prefer to write unit tests for my code, noting a test for each exit point in a code comment would take care of this. An automated check would just verify that the exit point has a notation.)
    • Make sure no E_STRICT warnings are thrown during tests

Note that any automation here is going to fail to really enforce anything: it is impossible to verify code-correctness completely without actually running the code. Instead the idea is not to verify that the code is bug-free, but just to make sure that I’ve caught the things that more experienced MW developers aren’t going to roll their eyes at. That said, the number of developers actively working on MW code as well as the CodeReview extension on make developing MW code an overwhelmingly positive experience. These things mean that — combined with the depth of PHP and MediaWiki knowledge and care that people take — problems see the light of day really quickly. When your code is likely to end up on one of the top-10 sites on the Internet, this amount of care is crucial.

In San Francisco

I’m in San Francisco for the day. Last night I had a great time with danlyke of Flutterby fame. Since right now is the the Advent Fast, he took me to Café Gratitude, a raw Vegan restaurant where every one of their dishes is an affirmation. I couldn’t help but giggle when they handed me my coconut curry soup as they said the mantra “You are Thankful!” I would imagine that The Secret has done better here than in Lancaster County. “But, Mark,” I can hear you not asking, “What the heck are you doing in San Francisco?” About a month ago, a non-profit here contacted me about a position they’re trying to fill. They need an open-source person to be, essentially, their community liaison for code contributions to their open source project. At the time, I was still working for IntraHealth, so I told them I wasn’t interested. But the following Monday, I found out I was not going to be working at IntraHealth any longer. A new (but smaller) round of funding came through and they just didn’t have room for me in the budget any more. With this new-found freedom from obligations, I called the HR person back and told him, “Guess what? I am interested after all!” In the meantime, this has been one of the more productive periods of transition I’ve ever had. Friends of mine who freelance have tossed a couple of gigs my way and I’ve spent a little more time with my kids. Only once have I glimpsed into abyss of fear and self-doubt that the recently jobless can end up in — the rest of the time I’ve been excited about the opportunities. So, here I am in a San Francisco hotel room early in the morning. My body is still on Eastern time and I can hear the city slowly coming to life around me. I plan on scoping out Berkeley this morning and then, after my interview (during which, in my fantasy, they offer me the job on the spot) I’ll go see how far CalTrain will take me.