David Baron's Weblog

As an implementor of specifications ("specs"), one thing that scares me when I read a spec is a requirement stated very briefly that requires lots of complexity in implementations.

Some classic examples of such statements are the statement from HTML 4.0 that “User agents should ignore empty P elements” or the statement from CSS1 that “Two or more adjoining vertical margins (i.e., with no border, padding or content between them) are collapsed to use the maximum of the margin values”.

These types of statements scare me for two reasons. First, in many (but not all) cases, it means that the required complexity won't be implemented the same way across implementations. In the examples above: Should the empty paragraphs be ignored by the parser and thus not appear in the DOM, or just not be displayed once they're in the DOM? What if script takes a non-empty paragraph and removes its contents? Should it disappear from the DOM? If it is then made non-empty, does it reappear? What makes margins adjoining? If the margins of a parent and its first child are adjoining (can they be?), where are the edges of the boxes? If an element whose top and bottom margins are adjoining contains floats, where are those floats placed?

Second, and more importantly, it means that the authors of the specification probably weren't aware of the complexity, and therefore didn't consider it when designing the specification. A major part of the job of a specification designer is to make tradeoffs: is meeting a particular requirement important enough to increase complexity, and thus make implementations more likely to be later or buggier? If the specification's authors weren't aware of the complexity, they probably weren't even thinking about the tradeoff.

When I was first involved in CSS spec development, I made the mistake of trying to remedy the first problem without also trying to remedy the second. Hixie and I wrote many proposals to make things that were unclear in CSS specifications more precise in a way that was compatible with the small statements that were in the specification. We treated little bits of spec as the incantations of an oracle, and demonstrated that there was only one way to satisfy all of them at the same time.

When we did this, we should have stepped back and reevaluated the requirements. (Given a specification that was then in use, there were additional compatibility requirements that didn't exist when the spec was written, but they often weren't significant, since implementations were often quite incompatible, which meant that content largely didn't depend on the areas where they disagreed.) For example, adjoining margins are now defined in terms of three pairs that make margins adjoining (plus the idea that being adjoining is transitive): (1) the bottom margin of one block with the top margin of its next sibling block (2) the top (bottom) margin of a first (last) child block with the top (bottom) margin of its parent and (3) the top and bottom margins of an empty block. There was a real use case for the first, and maybe for the second, but not for the third (other than satisfying the sentence in the HTML spec on empty paragraphs—a sentence I think was intended to break existing content to punish its authors for misusing HTML). However, allowing the top and bottom margins of a single element to collapse with each other increased the complexity of margin collapsing a lot.

So, I see two lessons from this. First, if you're writing a spec and you are aware of the tradeoffs, you should make it clear in the spec that you are (which also points out the complexity to implementors and testers). Second, if you're fixing a spec that's unclear, you should evaluate whether the complexity of the fix is really needed, or whether it's better to change existing parts of the spec to make better tradeoffs between complexity and features.