The Critical Moment in Software Design

Imagine yourself in a meeting with a user (or group of users) discussing requirements for a new software feature. At some point--usually about 15 minutes into the discussion--the following phrase almost always comes up:

"But that doesn't happen very often."

It's often said with an awkward expression or laugh. This is the critical moment. Behind those non-committal words the user is really thinking--"These are details. This is my world. Does this geek care about my world? No, of course not." Of course behind our geeky glasses and awkward social graces we care a great deal about the user's world. The detail of the user's world is critical. Without detail there can be no accurate design. If the design is flawed then everything else will be broken too.

My response is typically like this:

"Often it's those things that don't happen very often that cause the most trouble. If you don't mind let's dig into this a bit more?"

I have never talked to anyone who was't thrilled to go into great detail once they felt that they had "permission" to get into the details.

Why Don't We Document Our Software? Part 1: False Excuses

Quick what's the right answer:

a) We're bad writers

b) We don't like to write

c) We are too busy

d) All o the above

OK, trick question. The answer is: e) none of the above. Here is why:

a) Most software developers have at least a bachelor's degree from a liberal arts school. As a general rule we have at least as much training as the biology major writing the user documentation. Often we have more. Software developers write blizzards of email and fill up message boards with numerous comments. We can write.

b) If this were true why are so many open source projects some of the best documented systems out there? When programmers develop "for fun" we write documentation.

c) There is a kernel of truth in this. Everyone is busy. But the truth is we find time to do what's important to us (and our managers). Documentation just isn't.

In my next post I'll examine the real reasons we don't document our software systems.

My Code or Someone Else's Code?

Most software developers if given the choice of maintaining their own code or someone else's code, will choose their own. That's unfortunate. Editing other people's code is one of the best things that can happen to a developer. It's a great way to see what works and what doesn't.

Especially early in a career it's not always obvious what practices are best. Fixing problems in ten year old code is very revealing. My own coding style has become simple, spartan, structured and well documented. I didn't code that way in school or early in my career. I learned it as result of many, many hours of maintenance coding.

Working in someone else's code base is also good for the code. As I noted in my previous post, hacking in new code can be a very destructive process. When editing my own code it's very tempting to hack new features because I know where all the easy attachment points are.

It's not nearly as easy to hack in someone else's code without risking nasty side-effects. That forces a full re-evaluation of the code and often significant restructuring. The result is that the code ends up containing the best of both developers.

Coding is Bad For Your Code

There is nothing as destructive to a computer program as a good day of coding. An afternoon can wipe away a week's supply of simplicity and clarity. Gone are the clearly defined functions with well commented logic. In it's place is mess of IF and WHILE logic addressing all those special cases that didn't come up in the initial design.

We all know we "should" refactor. But the clock is a remorseless taskmaster. It's so easy to just hack in the feature we need and "design it better next time". Of course, there is no next time. Only now. There is no "design once, write once". Only design and re-design. Code by design, or hack without one--there is no middle ground.