Coding... a writer's perspective

I do a lot of typing...
I've been writing code for a long time...more than a decade and I've always wondered why the process of writing code couldn't be as natural as the process of writing prose.

Developing code is often considered an "engineering" activity. You can see this by the way many developers build code - starting with a design phase, which may include diagrams and specifications. Prototypes are launched. A lot of typing happens. Refactoring occurs. Testing, optimization and deployment soon follow. Not all of these are necessarily specific to this paradigm of the engineering activity, but there isn't much here that would lead me to believe that software development, and specifically the act of authoring code, is an art form.

I wasn't always a software developer. I got started as a writer -- the kind of writer who produces "copy" once a week -- and is able to produce that material consistently week after week facing a deadline. Usually, the writing process is something like this: get an idea, write an outline, take a break, sit down and work from the outline to write the whole thing in one draft, make a bunch of corrections, let it sit for a while, edit it a bit, clean it up, send it out.

Pretty different from the "engineering" activity you read about above. But, in many respects, a lot like the process of producing "code". To be honest, I tend to write code that way. Or, at least, I tend to borrow from the process of writing when producing code. I frequently jot down an outline of the major public methods. I may do a little research first.

I start to code. If the code starts getting too in-lined or isn't formatted in the way I like it (for example, if I see a long loop coming up or if a method is getting too long), I stop, scratch my head and get back to the outline.

When I'm finished a class (or a module in Visual Basic), I let it sit a while, if I can, then revisit it with an editor's eye. Is the formatting correct? How readable is the code? Are methods brief and focused?

The writer's craft has taught me a couple of other things I an not sure I see in the "engineering approach". Like all writers, I have a good idea of how much quality product I can put together in a period. I know that if I exceed that limit, quality suffers. I know that if I stray too far from my "outline-compose-rest-edit" methodology, things suffer. Sure, there are times when I can proceed fluently, like some great stream-of-consciousness writer. It all happens almost magically.... But these are more rare and I'm not sure they stray that far from the "methodology" I describe above.

The plot thickens...
When it comes to coding, the outline may start as an interaction diagram. By this time, I already have an idea of a plot (often it's something like either a functional specification or an XP story.) My big problem with the interaction diagram is that I find it difficult to start from it and effectively expand on ideas. For me, the diagram is a good place to start, but spread it out so I can attach notes and draw arrows and maybe add code snippets.

While all this is happening, the script has begun. While there are all kinds of doodles on paper and whiteboarding sessions, the coding has already begun. I have an image of what the code should look like. I may know of several methods that I have developed elsewhere that can be quickly re-coded and inserted. I know what spots are easy, what spots require research and what spots will be risky.

It becomes a kind of tension that builds while I work the inspiration and the ideas towards the moment when I can actually stick a piece of paper in the typewriter, take a deep breath and start typing. Often, this is done at home or in some spot where there is intense tranquility. (I'm not sure this is an advertisement for the modern work environment, but that's another issue....)

You hear a lot of talk about pair programming these days and I feel that while I haven't yet been on such a project, I would still prefer to start a first draft in private, then spin out a few ideas with another programmer. There's something about writing, whether it's code or Ulysses, that need peace and quiet. I've never seen writers effectively write in groups. (Although, I’m told it works well for writing scripts.)

While this has been a concern for a while, I have noticed that most programmers have a technique for structuring code that allows them to write fairly reliable code without endless re-writes. I think what many authors like Martin Fowler call re-factoring is actually the same sort of thing writers achieve with either the backspace key or the old paper ball in the basket. Most writers are self-editors to a large extent.

That doesn't mean they can complete the entire process without interaction with an editor and a proofreader. To my mind, this is where techniques like the programming pair can be highly successful. Have a second set of eyes run through the logic, suggest changes, and even spot potential bugs.

In Extreme Programming(XP) structured teams, the technique is pair programming, where groups of programmers get to share ideas and essentially design/write/edit on the spot. I think this is a great idea, where you have more than one programmer present. You get to bounce ideas and the two-heads-are-better-than-one factor means you can spot critical logic errors more reliably.

The only problem is that a lot of programming gets done by one person. Often, there are no teams. Or the lonely programmer writes code at home. I know that more than 50% of my code over the years has been written without the benefit of a team. Yet, I know that I can create reliable software in a non-team atmosphere.

Here are a couple of my techniques:

the Joshua Slocum method. Joshua Slocum sailed solo around the globe. To counter loneliness, he invented an alter ego against which he would bounce all kinds of ideas. My twist on this method is to write code, let it sit for 3 days, then try to read it. It's amazing how a 3-day respite can detach you from the guy who wrote the original code. A fresh perspective can spot all kinds of errors.

Test it. I normally add a few tests, which I place in the main method. A long time ago, I used to add a test() method, but I actually found the main method worked better. One thing I would suggest is including the tests in an open analysis with another programmer/editor. I find that a lot of tests I see written would be a lot more effective if they were really intended to break things. At some point, I think a product like JUnit could make testing a little less tedious.

do a legibility test. When you have some time away from the code, look at its structure. If you think it needs comments, there is probably something wrong with the code -- even if it works. On the other hand, when you see quite a few comments, you have to wonder if the code is unnecessarily complex. Is the formatting consistent with other code in the rest of the package? Does it rigorously follow the coding standards?

What does this mean to the lonely programmer
For programmers who have been around a while, the discipline of structuring code is something that we don't often talk about, but which we innately practice to deliver quality work. My suggestion is that through self-analysis we can continue to devise techniques that will raise the quality of our complex craft.

Any questions, please contact me Gervase Gallant.