Commit messages, tickets, and inline docs

As a Trained Academicâ„¢, I try to think about software documentation in terms of audience and purpose. Who is going to read technical docs? What will they be trying to learn by reading them? I use these questions as a lens for writing different kinds of documentation.

I like to think of commit messages as the canonical technical narrative of the project. These messages matter most for two groups of people: those following the ongoing development of the project, and those intrepid future souls who are combing through logs to track the lineage of given bit of code. The needs of the two groups are similar, which suggests certain content and formatting for commit messages. Both groups are scanning sizable streams of changesets, and thus need a quick way to disregard those that are irrelevant to them. That’s where the one-line summary is helpful, for git log and GUIs like this. Beyond the summary, they usually need a bit more context, a bird’s-eye summary of the problem the changeset is intended to fix. They need pointers to full discussions (ie, linked tickets). And because in projects like WordPress the changelog is also an attribution log, they need reference to the person responsible for the fix (“props”). It’s these kinds of needs I’m thinking about when I structure commit messages like this. (Side note: I’m a big fan of this post arguing for a similar commit message format.)

Tickets are bug notices or feature requests as they appear in the project’s issue tracker. The primary audience here is the developers, designers, and users who are currently involved in the ongoing development of the software. It’s a workspace, and it’s messy. Tickets may contain extended discussions, with numerous digressions and dead-end patches. It’s for this reason that issue tickets are not a replacement for good commit messages. Commit messages contain justification for changesets, while trackers contain the process that led to that justification.

Inline docs, primarily in the form of function/method/class docblocks, are intended first and foremost for developers who are currently trying to figure out how the software works. As a rule, these people don’t care about the history of the project, or the reasoning that led to a given piece of code. The documentation should answer questions like: where is this function used in the codebase? if I put x into the function, what will I get out of it? etc. While it’s often good to have pointers to the project history in certain cases – such as a link to a ticket that explains why an unintuitive bit of code works in the way it does – it probably does more harm than good to litter inline documentation with details about the project’s intellectual history. That’s what blame tools are for.

It goes without saying that there are gray areas. Commit messages, tickets, and inline docs all have the same “text” as their subject: the codebase. And the intended audiences for the three kinds of documentation are frequently overlapping. Still, I think it’s helpful to keep the distinctions in mind. When you write documentation, you’re writing the story of the project as it’ll be understand by future coder-historians. You want to make sure that the story makes sense.

A less finicky BuddyPress search

BuddyPress search, out of the box, is not very good. Say you’re looking for a group called “History of Wars in America”. The search term Wars in America will return the group, but America Wars will not. (Technical reason: search terms get lumped as a single string into a MySQL LIKE clause.)

I have some ideas about how to improve this behavior in BuddyPress itself, including stealing some of the goodies that recently went into WordPress. But for now, here’s a simple drop-in filter that fixes the word-wise problem.

(if the formatting is messed up, view the original at https://gist.github.com/boonebgorges/8301715)

Something very similar would work for members searches, though the query variables passed along to the filters probably have a slightly different syntax. (I made these changes for City Tech OpenLab, whose members queries are custom anyway.)

Again, this filter is not perfect – it doesn’t try to do any caching, it doesn’t look for literal strings in quotes, etc – but you might find it useful until some real fixes are in place in BP.

Affirmations for the free software developer

A friend recently came to me to express some frustration. He’s the leader of a relatively new free software project, and was having his first run-in with a user who was making extensive, arguably unreasonable support demands, in a tone that was increasingly hostile. If you’ve ever contributed to a public project, you have probably had similar experiences.

I responded to him with the following words of “wisdom”. Nothing terribly original here, but I have to remind myself of these points on a regular basis.

  • For every one user who engages with you in an unpleasant way, there are 10 users who provide feedback and request support in a friendly and reasonable manner, and 100 people who are using the software happily and asking for nothing.
  • People only bother to complain about something if they care about it.
  • Obviously, you want to be fair and kind to people who come to you for help. But your capacity to give a shit is like currency: it exists in finite quantities. It’s better to spend it on something that’ll provide positive good in the world, than to dump it into a bottomless pit.

Brooklyn is for runners

I lived in Brooklyn when I started running in my mid-twenties. I didn’t know it at the time, but I was spoiled.

I never really enjoyed running for its own sake. I did it because my then-girlfriend (now-wife) was a serious runner, and because I wanted to continue to eat and drink as I pleased without risking my girlish figure. I managed to tolerate running thanks only to my Brooklyn backdrop. Over the course of about five years, I ran some 5,000 miles on Brooklyn’s streets. It was my way of learning the grid. From Williamsburg, I got to know Greenpoint, Bushwick, Fort Greene, Bedford-Stuyvesant, Crown Heights; from Park Slope, it was Windsor Terrace and Kensington and Sunset Park and Bay Ridge; from Carroll Gardens, it was Red Hook and DUMBO and the waterfront. I have a decent mental map of maybe a third of Brooklyn’s seventy square miles, thanks to these here legs.

So I came to think of myself as an “urban runner”. Pounding the pavement was my way of getting to know my surroundings, and soaking up the city was my way of coping with running.

Then I moved to Queens, and everything changed. I’m not talking about Whitestone or Hollis or Rockaway or some other deep-Queens neighborhood. I lived in Ridgewood, about five blocks from the border with Brooklyn. But it was a totally different world. The car-to-pedestrian ratio was out of whack, which resulted in a totally different relationship between drivers and non-drivers. Instead of grumbling deference, I came to expect outright hostility from cars. I can’t count the number of times a driver sped up – or ran a stop sign – to beat me through an intersection. I even got hit once (albeit slowly), even after having made eye contact with the driver.

To make matters worse, Queens (or at least my portion of it) was boring. The semi-suburban neighborhoods bleed together in my mind: Glendale, Elmhurst, Woodside, Maspeth, Middle Village, Forest Park, Woodhaven. I know Queens is a (ethnically, linguistically, culinarily…) diverse place, but I could take or leave the bafflingly numbered streets/avenues/lanes/courts and single-family houses.

I moved to Manhattan a few months ago, where I hoped to recapture my love of urban running. It hasn’t gone well. Too many cars, too many people, too many stoplights, too much street construction. Dodging walkers on the sidewalk isn’t fun for me, and it isn’t fun for the people being dodged. Central Park is very nice, but I’m bored with it already.

In retrospect, Brooklyn is the perfect balance for the urban runner. It’s dense enough to be interesting. Neighboring neighborhoods contrast sharply with each other. Cars – at least in the northern and eastern parts of the borough – are few enough (and deferent enough) to make it safe to share the streets. I miss it.

If you are a runner living in Brooklyn, fight the urge to stick to the well-trodden paths. I too love Prospect Park, and the Belt Parkway Promenade, and Brooklyn Bridge Park. But you should be out on the streets, because there’s no better place to run.

Book purge

About six months ago, I began to get rid of my books.

I’ve grown to dislike owning books. They’re heavy, take up a lot of space, and are generally pretty ugly. So many are phantoms of former lives, stirring up icky feelings – guilt, remorse, disgust – every time their spines catch my eye. I have a strong distaste for many of my old academic philosophy books in particular, but at the same time I feel guilty that, however lousy I might think they are, they’re sitting unread on my shelf when they might be of use to someone else. (It’s odd that the people who fetishize books the most are those most likely to hold them hostage.)

It’s not that I’m reading less. I’m a regular at my library. I occasionally read e-books (though I don’t care for them). I still even buy books. It just seems weird to keep them. The only copies worth keeping are those with sentimental value and those that I’ll read over and over again. This covers about 1% of the books on my shelf. The rest? Off they go.

I considered a bulk donation to charity. But this wasn’t enough of a Project, so I put them on Amazon instead. As others have noted, many books are not worth much. Between time spent listing, time spent packing, time spent at the post office, money spent on envelopes and tape, and Amazon’s fees (which have a floor and thus are particularly hefty for very cheap items) it’s often hard to break even on a sale – and that’s not even counting what I originally paid for the book! I’ve sold about 100 books to date, clearing around $600. Obviously I’m not getting rich. It’s a good thing I’m not doing it for the money.

The best part about selling the items individually is that each sale is like a little going-away party (or funeral, depending on the book). Amazon sends an email – “You’ve sold an item!”. I track down the title on my for-sale shelf, give it a last once-over, pick out any old bookmarks. I make up little stories about the buyer, based on her name and address, making comments to myself along the lines of “Reading Quine? My condolences”. I stand in line at the post office, so that I can send via Book Rate. I enter the total earned into my fancy spreadsheet. It’s a ritual that gives me a chance to reflect on the book one last time before sending it to a better place. I like it.

As the shelves grow barer, I walk a little taller. It’s nice.

Vim function for correcting whitespace to WP standards

When doing client work, especially in a team, I like to urge adherence to the WordPress coding standards. This is especially important with whitespace, in particular when other members of the team have their IDEs set up in certain ways that frustrate the standards. I wrote this quick little functions for your .vimrc that does some whitespace cleanup in the currently open buffer. (I’m sure there are a thousand better ways to do it, and you should feel free to let me know in the comments. This is just what I put together in 15 minutes.)

I’ve mapped it to F8. Modify as you’d like.

2013

Another installment in my year-end reflections.

In my 2012 post, I laid out a couple of things to think about during the upcoming year. I feel like I did a pretty decent job with at least one of them: turning off. This summer, my family and I rented a cottage and vegged out for a month and a half. I intended it to be a semi-working vacation, but it ended up being a barely-working vacation, and it was awesome. I also made some changes in the second half of the year that made me more mindful of getting sucked into work while on the go: I stopped using email on my phone, I got myself an OFF Pocket, and I’ve generally stopped carrying my phone so much. I started riding bike for fun around the city, and got back into a decent running routine (about 800 miles on the year). So, I feel like things are a bit more relaxed than a year ago.

Work-wise, I haven’t branched out as much as I’d hoped. I’ve got a few big deadlines in the next month or so, after which I plan to come up with an interesting project or two to shake out some of the cobwebs. If anyone is planning to do something really cool, let me know :-D

I continue to feel less and less connected to my old academic self. This is something I don’t talk about much, either online or in person, though I was recently persuaded by a friend that others might benefit from hearing about it. In the upcoming year, I hope to write more about this issue and other more varied topics than what I allowed myself in 2013.

Out with the old. Happy new year!

Where is the artisan bagel movement in NYC?

Moving to New York, I was excited about two things: pizza and bagels.

Pizza did not disappoint. NYC’s pizza landscape is rich, and has become richer over the last decade. There are overlapping ecosystems for dollar slice joints, traditional slice joints, and hybrid slice/Italian food joints. There’s a stratum of old school NY pizza restaurants: Totonno’s, Arturo’s, Sam’s, etc, as well as the newer places that aspire to a similar aesthetic. And there’s whole class of artisinal, neo-Neopolitan places, where foodies shell out big bucks for bufala. You could eat pizza every day and never hit every place.

The bagel landscape is perhaps equally complex. But it’s bottom-heavy in comparison to pizza. You’ve got the guys in the silver street carts who sell bagels pre-filled with a slice of cream cheese wrapped in wax paper. There’s the bullshit bakery chains, the Panara-Dunkin-ecticut-n-crustys where bagels are an afterthought to other baked goods. And then there are the mainstays, the neighborhood bagel shops. Like neighborhood slice joints, the quality of this category varies widely, from shoulda-had-a-Lenders to the Bagel Hole (the only really outstanding bagel I’ve ever had, in NY or elsewhere).

But where are the artisan bagels? Dom Demarco has people lining up for $5 slices at Di Fara. There’s gotta be a similar market for someone to sell outstanding bagels – small, properly boiled, without preservatives – even if they charge a premium for them. I get that it’s not glamorous: stirring a pot full of boiling bageloids in a dingy kitchen doesn’t have the sex appeal of wielding a peel in candlelit Lucali. And I get that bagel-place-as-destination is hard to fit into the geography and the late-night culture of New York. At the same time, a great bagel can be just as fantastic as a great slice, and IMHO is just as important a part of NY food culture. Where are the hipsters lining up to continue this particular foodways tradition?

Maybe I’m way off here, and there is actually a bagel subculture in NYC that I’ve never stumbled on. I hope someone’ll clue me in.

How to pronounce ‘Gorges’

I grew up in a town of about 5,000 in northeastern Wisconsin. Of those 5,000, probably 200 had the last name ‘Gorges’. People with the name had been in the immediate area since the 1850s, when my great-great-great grandfather Gorges migrated with his family from Pomerania. As a child, I took for granted that it was a “normal” name, and that everyone knew how to pronounce it.

When I was in ninth grade, my family moved. Our new home was just 25 miles from the old one. But few in our new town knew anyone with the name ‘Gorges’, and no one knew how to pronounce it. We quickly adopted a modified pronunciation of ‘Gorges’, one that was meant to better match the way it was spelled (GORE-guess). The improvement was marginal. Preemptive spelling became a coping technique. When asked for my family name, I would (and still do) often omit the pronunciation altogether and skip straight to G-O-R-G-E-S.

As an adult – living far from the epicenters of Gorgesdom – I started to think more critically about the whole situation. Years of experience had shown that any pronunciation, however modified, was going to require a follow-up spelling. That meant that, in exchange for a pronunciation that never felt natural, I wasn’t getting any practical benefit. As a teenager, I’d switched because my family had switched. But my family is far away now. And if there’s any one normative fact about the world that an individual ought to be able to dictate by fiat, surely it’s the “correct” way to pronounce his name.

So I went back to my native pronunciation, which my wife and son use as well. Which is different from the (modified) pronunciation still used by my father and (I’m pretty sure) by my younger siblings. It’s an odd state of affairs.

On balance, I’m actually a pretty big fan of having an unusual last name. The “gorgeous” pun is a dynamite icebreaker, especially for someone as good-looking as me. (See?) Some people are quite particular about the way others say their names (which is within their rights), but I long ago learned not to care very much, to the point that I’ve never offered corrections even to some fairly good friends. This nonchalance is like tossing off a burden I’ve carried since I was a kid. And – bonus – my usernames are never taken.

[For the record: two hard Gs. GRR-ghiss.]