Yet again, Linus Torvalds seems determined to do more harm than good to the world of programming. Here’s why he hates specs.

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.

I know a lot of people who’ve been doing kernel programming longer than Linus (I’m one) who would take this as evidence that he should get out of the specialty immediately. His “when reality and specs clash” comment is almost true when you’re talking about interoperability with devices or APIs between companies, but not quite. There are still vendors who will respond reasonably if you point out how their product violates a spec. I know because I’ve been on both sides of that kind of interaction, in the specific domain of storage protocols which spawned this email thread.

When the clash between reality and specs occurs within the context of code where you control both ends, Linus is almost totally wrong. Reality can be changed, and often should be changed if it makes a program more efficient or more extensible or more maintainable etc. Programming is all about changing the reality of version N into a new reality of version N+1. A spec is no more than a statement of what the new reality should look like. It can also serve as a starting point for a dialog about that new reality, before too much of everyone’s time is wasted by incompatible unilateral changes to the code. Yes, a spec for version N+1 might become outdated when people start to think about version N+2, but that’s no different than what happens to code. The fact that reality tends to keep moving can be managed in either case. Demanding impossible perfection of specs and presenting far-from-perfect comments in code as an alternative is shoddy both in theory and in practice.

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.

Again, there’s a small nugget of truth buried in a big pile of Linus BS. Some people, especially some of the extreme UML weenies like those (at Rational) who used to occupy the building I’m in now, seem to believe in “executable specifications” and such. I think they’re full of it, and Linus is right to say so. However, Linus then falls prey to an argument from ignorance: he doesn’t know how to write a useful spec, therefore he concludes it’s impossible. I’ll put that another way: Linus is incompetent at a core software-engineering task. This kind of non-reasoning is common among people who think they’re the smartest person in the whole world, and particularly among those who have spent too much time basking in the adulation of ignorant fan-children who wouldn’t know good code if it got into a robot and literally bit them on the ass. It also reminds me of the people who claim that government is inevitably inefficient and corrupt only because government run by them is always that way and they can’t imagine how anyone else could be better.

In fact, there are many good specs out there. Many of the old network-protocol specs out of DEC were excellent, not just in the abstract but in a very concrete way that made them useful to people actually trying to implement interoperable hardware and software. The specs for SCSI and its descendants such as Fibre Channel, by contrast, are pretty awful. They were packed full of flags and features that were almost universally ignored or unused except by the one standards-committee member who demanded them, while they simultaneously left way too much slack in important areas such as error reporting – when errors are reported, to whom, when they’re cleared, what the codes mean, etc. I think it’s reasonable to say that protocol/API specs designed by committees generally do suck. However, design specs written by a single person are a whole different matter. Any decent software engineer should be able to write a spec that explains how something works, well enough to help the next person who works on it and far better than comments in the code itself (not an area where Linux shines BTW) could ever do. Linux itself has often been hurt by the lack of specs. I still remember when the VFS Layer from Mars was introduced, and there were tons of bugs that resulted from nobody understanding the new interfaces and particularly the new locking schema (which kept changing anyway). That somebody who lived through that could still recommend winging it just boggles the mind.

What’s more disappointing than Linus’s behavior (which is no less than I’ve come to expect) is that Theodore Ts’o – someone I’ve met and who generally seems much more reasonable – chose to back him up).

This is one of the reasons why the IETF doesn’t bless a networking standard until there are multiple independent, interoperable implementations — and even _then_ there will be edge cases that won’t be caught until much, much later.

…and yet, the IETF does use specs, and we wouldn’t be having this conversation without them. That such a thing should be true is just more proof that, contrary to what Linus and Ted claim, writing good and useful specs is possible for people who know what they’re doing. Yes, there are plenty of bad specs out there, but pointing only to them is dishonest. Some specs are over-layered and introduce too many unwarranted abstractions (I-T-L-Q nexi, anyone?) but that doesn’t mean all specs are bad. There are also good specs. A responsible engineer who actually has an interest in quality and productivity instead of ducking responsibility should learn the difference, not just refuse to do what they personally find difficult.