...according to Linus Torvalds. I have to chime in on Linus’ newsgroup posting and the attendent buzz it sparked on the net this week (and on the Linux Kernel mailing list). Linus stated:

So there’s two MAJOR reasons to avoid specs:

- they’re dangerously wrong. Reality is different, and anybody who thinks specs matter over reality should get out of kernel programming NOW. When reality and specs clash, the spec has zero meaning. Zilch. Nada. None.

It’s like real science: if you have a theory that doesn’t match experiments, it doesn’t matter how much you like that theory. It’s wrong. You can use it as an approximation, but you MUST keep in mind that it’s an approximation.

Specs have an inevitably tendency to try to introduce abstractions levels and wording and documentation policies that make sense for a written spec. Trying to implement actual code off the spec leads to the code looking and working like CRAP.

He went on to conclude:

“But the spec says ...” is pretty much always a sign of somebody who has just blocked out the fact that some device doesn’t. So don’t talk about specs. Talk about working code that is readable and works. There’s an absolutely mindbogglingly huge difference between the two.

This posting launched an onslaught of discussion. Linus is right. Reality always differs from a specification of how software is supposed to behave. That’s a reflection on how difficult it is to write precise specifications of behavior and on how many decisions during implementation are left open. Still, I’m not willing to say “no specs, ever” even though I’m a signer of the Agile Manifesto and on the board of the Agile Alliance. We need to get better at recognizing what types of descriptions do add value and under what circumstances. And become more aware of when and where precision is needed (and when it drags us down).

Linus points out that specs often introduce abstractions and concepts that shouldn’t be directly implemented in code. I never expect to directly translate what someone writes into code without using my brain. I design and think before and during and after coding realizing that nothing substitutes for testing/proving out a design and implementation against the real environment it works in.

But that doesn’t mean specs have no value. Working, readable code isn’t the only thing that matters. It matters very much in the short and long term. But try understanding design rationale by just reading code. Or reading the test code. It’s difficult, if not impossible. I find value in design documentation that explains the tricky bits. This type of documentation is especially valuable when those coding aren’t going to hang around to offer explanations.

A spec is an approximation of what is desired. I certainly don’t expect it to tell me everything. There can be enormous value in writing descriptions of what software should do, especially when it is important to communicate design parameters and system behaviors instead of just providing an implementation. Most developers aren’t good at writing specs, let alone descriptions/discussions about their code and design choices. But that doesn’t mean they should stop writing them and resort to “organic code growth”in every situation. A firm believer in agile practices, I don’t insist in writing merely for fun or because it is expected. But if I need a spec, I write it. And if doesn’t reflect reality or is misunderstood, I change it if there is value in keeping it up to date. There may not be. And if that’s the case, I don’t update it. It depends on the project and the need. It helps if I write these descriptions for someone who wants to read them (and will actually use it rather than toss it aside). I’ve got to know my audience. That often takes experimentation. Maybe I need to include sample prototype code in addition to design notes/models/sketches. Maybe I don’t. Communicating ideas to a diverse audience is especially hard. But specs aren’t the problem. It’s that effectively communicating how something works or should work is more difficult than cutting code. I prefer working code over piles of outdated, difficult diagrams and explanations. But that doesn’t duck the issue. Specs aren’t inherently bad. Most spec writers would rather be doing something else. And that is a problem.