Because I am Clearly an Expert on Style

Rob Donoghue asks:

How critical is a unified style/formatting guide for developers in an agile environment? On one hand, the common formatting would seem to help the hand-off, but on the other it seems it might be seen as an unnecessary limitation.

My first instinct is to say, “Not at all. You’re pair-programming enough that the style comes reflexively, rather than being prescribed by a document.” Given that I’ve just been working on the coding standards document for our teams, however, I realize that’s not always as true as I want it to be.

What it works out to is that you have to document what you can’t talk about. We’ve got three teams split across four different locations, so we have to rely on documentation as a replacement for conversations more than we would like. We do try to write just enough to put the right ideas in people’s heads, and nothing more. Documentation can’t substitute for judgment. It can tell people what to worry about. Here’s how our coding standards start:

At a high level, we want to embody these concepts:
* Correctness, simplicity, and clarity come first
* Do not prematurely optimize
* Do not prematurely pessimize
* Hide information
* Give each entity one cohesive responsibility
* Ensure resources have owners
* The compiler is your friend

We maintain this on wiki page; each of those bulleted points links to a page with more detailed information about specific ways we try to enact the principle.

A lot of my thinking about this has been influenced by Ron Jeffries’ Card-Conversation-Confirmation model for user stories and the Agile in a Flash cards (whose authors also have something to say about coding standards). What is written is a spur to have a conversation, so write only enough to get people talking about the right things.

Update

Fitness: Ran 2.25 miles + 30 minute workout
Writing: 383 words, 267 average

Working Mindfully

Ricky asks:

I read this the other day and I was wondering if you had heard about this or if you have experienced or seen this?

I hadn’t seen it. As I turns out, I have a ton of responses to it, shotgun-style.

• “Process” in this article seems to be shorthand for “things I don’t like doing.” Hard to argue with the notion that it’s not fun doing things you don’t like.
• Turns out, all programmers have process, whether they like it or not. Unless you take a completely different approach to writing code every time you sit down at the keyboard, you work in a particular way. How you work: that’s process.
• I have an inherent distrust of anyone who says “I’ve learned all I need to; the way I work is perfect.” I don’t care if you’ve been programming for thirty years. The world is always changing around you, and you need to change with it.
• Every job has less pleasant parts to it. That doesn’t mean that you get a pass on those parts in the name of “maintaining your passion.” Passion is one thing. Craft is another. If you can’t maintain your passion in the service of your craft, you’re not as passionate as you think.
• Now, the mindless application of process is something I am opposed to. There needs to be a reason why you do certain things. I don’t think this focus on process and metrics is new at all. Look back at CMMI or at structured programming. Every software process or technique ever assembled was developed to harness the current understanding of how projects and programs fail in an effort to improve how things are done. There are reasons why these ideas are put together. Programmers need to understand them in order to figure out what processes and techniques can help them in their current circumstances. Just as we shouldn’t adopt processes mindlessly, we shouldn’t reject them mindlessly either.
• The profession of programming is much, much more than writing code. If that’s all you want to do, don’t pursue it as a career. Keep it as a hobby. Being a professional means spending a lot of time asking “What code do I need to write?”, “What code do I not need to write?”, and “How do I know that the code I wrote does what I intended?” Those questions, to my mind, are what every software process try to help us answer.

I could go on, but I think that’s the stuff that’s worth saying.

Update

Fitness: Biked 10 miles
Writing: 413 words, 269 average

Quick, Often, and Clean

Karl M asks:

More refactoring please! What techniques do you find yourself using? What do you love about it? Aesthetics? Patterns? ‘Craftsmanship’?

The phrase that’s stuck with me over the years is “ratcheting in the gains.” I first encountered it in a programming context sometime around 2002. I don’t remember where anymore, but it was probably in one of the XP books. I’ve carried that idea with me and used it as an ideal for years.

You see, the biggest problem I’ve seen on software projects I’ve worked on is moving in the wrong direction. When schedules slip, it’s not because we haven’t been moving forward fast enough, it’s because we’ve actually been moving backward. Developers break existing code without realizing it all the time. Unless, of course, they have a ratchet.

In the physical world, a ratchet is “a mechanical device that allows movement in only one direction.” In software, it’s something that makes sure that your changes are not breaking existing functionality. Having a comprehensive regression testing suite is the answer most developers have to this problem. That is necessary but not sufficient.

Refactoring and other agile software techniques recognize that in order to act as a ratchet, regression testing has to happen at the same frequency as coding. The cycle time of your test feedback needs to be roughly equal to — if not less than — the amount of time it take to make a code change. Running the tests, seeing them clean, and committing the code to version code is what setting a ratchet point is in software. Until you’ve done all three, you can still move backwards.¹ After that, you’ve always got a known good point.

Another critical piece in ratcheting in the gains is setting those ratchet points as often as possible. I’ve seen material that indicates Agile developers commit code to version control ten times more often than non-Agile developers, not because they work ten times as fast, but because they see how to split the work into slices ten times as thin. I’ve seen my coding undergo exactly this transformation over the last year as I’ve started to use refactoring and TDD more effectively. Last week I did in six steps what I used to do in a single shot, because I’ve seen the value of being able to revert at any point. It’s like setting chocks while climbing: The closer together you set them, the less far you can fall.

The third critical ingredient that turns a regression test suite into a ratchet is the attitude that the tests always have to run clean. There’s no such thing as a “known failure.” If a test fails, you stop the line and fix it. If your tests are comprehensive, fast, and run often but you let them fail, you’re letting yourself move backwards.

Having that ratchet, climbing with those anchor points, is probably the thing I love most about refactoring. I can make changes to code much more quickly than I could before. Some people think that it’s odd that one of the XP values is courage, but my experiences over the last year have shown me why. In order to respond to changes — to truly be Agile — we have to have the courage to make quick changes to our code. It’s not foolish bravery, because we’ve taken the right precautions. We’ve made sure that we can’t go backwards, only forwards.

Update

Fitness:
Writing:

fn1. There really is a fourth step, which is seeing everything run clean in the production environment. Getting these three in place is still quite an accomplishment for a lot of teams and developers.

Laying Down Track

I love refactoring, perhaps even more than writing new code.

For those of you aren’t software geeks, refactoring is the process of changing the structure of a body of code without changing the behavior. It’s about redesigning code so that does the same thing as before but in a different way. Usually you do this because you’re going to add new behavior to it, but the current design doesn’t allow you to. There are other reasons, but that’s the big one.

I just spent an hour working from home on a weekend, which I never do, because of something I realized late yesterday afternoon.

The project I’m on at work has a lot of what one of my co-workers described as “hand-crafted code.” The code does exactly what the first release of the product needed to it to do, and nothing more. In one way, that’s a good thing, because it wasn’t overbuilt. In another, it’s not, because the code is fragile and hard to re-use. Even worse, much of the code uses the Big Ball of Mud design pattern. There are lots of long methods, objects with multiple responsibilities, and modules that are hodgepodges of different pieces of functionality.

What I realized yesterday afternoon was how to eliminate two unnecessary and confusing functions from a module’s interface. This particular bit of code has been vexing me for quite a while, so I take any chance I can to clean it up. And as I moved the code around today, it really sunk in how much I love this kind of work. I love seeing the potential in a body of code, working within the current constraints, improving what is there. There’s something about the process of refining, of letting the new design emerge, that hooks into the synergistic part of my brain. A lot of my role on my current team involves taking functionality that other people have developed and making it work in ways or in situations they didn’t originally design it for. Other people can blaze the trails. I’m happy building the railroad behind them.

Update

Fitness: Ran 2.25 miles
Writing: 448 words, 258 average

Wrestling Code Into Shape

I’ve been up to my eyeballs in code at work, which is both a good thing and a dramatic change of pace for me. My officemate and I have been untangling some code so that we can test it. To that end, I am indebted to the following books:

• Refactoring by Martin Fowler. I first read this book almost ten years ago. It’s only in the last month I’ve gotten heavy use out of it.
• Working Effectively With Legacy Code by Michael Feathers. I’ve read this more recently, and it accurately describes the situation I’m working in right now. It lays out remarkably useful, methodical processes for dealing with these sorts of hairy situations.
• C++ Coding Standards by Herb Sutter and Andrei Alexandrescu. This has provided the vocabulary to describe to other developers what’s wrong with our existing code. I ended up writing an email today that said, “The problem with the current design is that it violate principles #5 (‘Give one entity one cohesive responsibility’) and #34 (‘Prefer composition to inheritance’).” And the person I sent it to completely understood.

Since I got back from skiing, my head has been full of code. I suspect that will continue for a few days yet. It’s good thing I enjoy it.