Status

What I’ve learned so far about consulting work:

  • Harvest feeds the OCD time tracker inside of me.
  • Creating proposals is a huge time suck.
  • There’s so much room for automating all of this.

Advantages of code review

Advantages of pre-deploy code review, over post-deploy audit:

  • Authors have a strong incentive to craft small, well-formed changes that will be readily understood, to explain them adequately, and to provide appropriate test plans, test coverage and context.
  • Reviewers have a real opportunity to make significant suggestions about architecture or approach in review. These suggestions are less attractive to adopt from audit, and may be much more difficult to adopt if significant time has passed between push and audit.
  • Authors have a strong incentive to fix problems and respond to feedback received during review, because it blocks them. Authors have a much weaker incentive to address problems raised during audit.
  • Authors can ask reviewers to apply and verify fixes before they are pushed.
  • Authors can easily pursue feedback early, and get course corrections on approach or direction.
  • Reviewers are better prepared to support a given change once it is in production, having already had a chance to become familiar with and reason through the code.
  • Reviewers are able to catch problems which automated tests may have difficulty detecting. For example, human reviewers are able to reason about performance problems that tests can easily miss because they run on small datasets and stub out service calls.
  • Communicating about changes before they happen generally leads to better preparation for their effects.
Quote

I like to think of funded startups vs. bootstrapped web sites like the split between signed and unsigned bands.

Think about what a band has to do if they sign with a major label. They write music, perform/record it, and play it. Now think about people like Prince, Aimee Mann, etc. that do every single aspect of their music themselves. They have to create and record and distribute music, but also book tours and hotels and hire roadies and even oversee building websites. On the positive side, those going their own way talk about making more money from lower record sales than they did on a label, even though they do a significant amount of work.

So it’s a lot of work, but I would argue it’s totally appropriate for anything that isn’t a huge world-changing idea. And there are a lot of benefits that come from it.

Matt Haughey — My Webstock Talk: Lessons from a 40 year old (now with transcript).

What makes a good commit message

There’s a useful conversation happening in an internal Automattic P2 I thought I’d take the liberty to share.

From Mike:

Consider the audience when you write a commit message. What is that audience? It’s at least two groups of people:

  • Your coworkers: You’re telling everyone else what you did. Commit messages are one to many, asynchronous and textual. Sounds like email, so write the commit message like an email. The first line should be a descriptive subject. The next line should be blank (as a separator). Then comes the body of the message. Write everything as if you’re describing it to Nikolay.
  • Your future self: Think back on the times you were fixing something and needed to understand why an old commit was made. How often was the commit message useful? How often was it your own useless commit message? The commit message should say what the problem was (repro steps?), how you fixed it (briefly – the code itself gives more details), and why you changed what you did. That way the shiny pants people of the future have the information they need to decide if they can safely change your code.

From Matt:

I think as a company we need better commit messages. Very often in our messages we say what is happening but not the why, and most importantly the context of the change. I’m going to pick on this changeset, but you could really pick almost anything:

[link to changeset]

4 lines changed, with the message:

“Fixing incorrect $blogid variable, should be $blog_id.
Check if $current_blog is === false before trying to reset it.”

First a good thing: it’s a multi-line message, which is nice. Commit messages can use as many lines as you like, and be as verbose as you like.

However if I were to come across this changeset 3 years from now, say if I were debugging a similar area in the code, I’d have no idea why this change happened. The message might as well be blank, since it doesn’t really say anything I couldn’t tell in 2 seconds from looking at the diff. Some useful context would be:

  • What bug did this code cause? (This is most important.) Why change it?
  • Is there a relevant discussion, either on a P2 or in Trac?
  • Who was involved in the fix, IE who else would have context for this change either because they reported the bug or reviewed the fix.

From Lance:

Good commit messages are my gospel. The actual syntax should vary by context, though. For theme commits, for example, we always start with the theme name up front.

But, the goal of giving context and pointing to related items is key.

I personally don’t think long commit messages are better. Instead, point to a Trac ticket or P2 post with all the gory details.

Aside

Writing beginner level tutorials. A number of useful tips. My favorite: “use words and phrases that your reader can Google to find more information.” For producers of documentation, I think the biggest challenge is putting yourself in the mindset of the reader. The second biggest challenge is closing the feedback loop between the person who has the knowledge and the person who wants the knowledge.