I’m still working through RFC 2980 while implementing my NNTP server, Wombat. I’ve gotten to the point where I’m implementing the LIST SUBSCRIPTIONS command. The problem is the documentation in the RFC on this command is a bit light:
This command is used to get a default subscription list for new users of this server. The order of groups is significant.
When this list is available, it is preceded by the 215 response and followed by a period on a line by itself. When this list is not available, the server returns a 503 response code.
There are a couple of missing pieces of information here. First, the comment “The order of groups is significant” worried me. Why is the order significant? The answer to that question would effect how I implemented the command. Does the order need to match the order returned by the LIST command, which lists all possible groups? Does it need to be in hierarchical order (i.e. alt.startrek comes before alt.startrek.deepspace9)? Does the client assume any new default groups will be added at the end, so it can easily pick them up?
I search the ‘net for an answer, but couldn’t find anything. I had INN installed, so I went searching through its code and man pages. That’s when I learned that order was sometimes important because it would be presented to the user in that order. Therefore, more important groups for new users should be towards the top. That’s the only reason order is “significant.”
The second missing piece of information I didn’t even notice until I started trawling through INN code. I had assumed the returned list of groups would be formatted the same as LIST and LIST ACTIVE. That is, it would be the group name followed by the start and end article number, and if posting is allowed. However, I discovered by looking at INN that it was simply a list of group names, each one on its own line. The format of the list isn’t mentioned anywhere in RFC 2980.
This is what the RFC sometimes refers to as “documented in code.” This term is very misleading. What it really means is “this isn’t documented at all, plus we will actively try to mislead you.”
I’ve had to deal with “documented in code” before. Back when I was working for Macromedia (now Adobe), I implemented the MX interface on the Mac. The MX interface was cross product branding, intended to make the panels used in all the different products (Dreamweaver, Flash, Fireworks, and FreeHand) look and feel identical. The Windows side had been implemented first. When I asked for a specification to implement, I was promptly told to just make it work like Windows.
I wanted to throttle the person that told me this. There were several problems that this caused.
First, I spent a lot more time implementing this feature than I should have. That’s because I had to dig through Windows code, and test the Windows code just to figure out what I was supposed to be implementing. I was further hindered by the fact that the Windows code was sample code, not shipping code. i.e. Not only was it Windows code, it was poorly written Windows code. Contrast that with the effort needed to read and understand a well written specification. By the way, I was assured we “didn’t have time” to write a specification for the feature.
Second, the specification was continually changing. I wasn’t told about any of this, nor was the Windows sample code updated as frequently as it should have been. The designer would simply occasionally come into my office and tell me something didn’t work right. I have no idea how the QA people figured out what was a bug and what wasn’t. I certainly didn’t know. As a result, I managed to faithfully reimplement bugs in the Mac that were in the Windows sample code.
Thirdly, there were some Windows idioms in the sample code that didn’t translate into Mac idioms. I had to question the designers about it, and often got a wishy-washy answer or no answer at all (“we’ll get back to you.”).
Trying to figure out a specification by looking at an implementation is nigh impossible. It’s difficult to determine what’s an implementation detail and what’s really part of the spec. It forces you to know and understand an entire software system, just to figure out how a certain feature is supposed to work. It’s very easy to miss a small detail that changes how the feature works entirely. That’s what I meant by “…plus we will actively try to mislead you.”
It also means that the specification is often incomplete. The implementation only deals with the specification from one perspective. i.e. If it’s a server, it only implements a command, it doesn’t show how a client might deal with the response of the command. As with the MX interface, the Windows implementation said nothing about how Mac specific details should be implemented.
If you trying to define a specification, reference implementations can be very helpful. However, they are not a specification. Until you have a real specification, don’t claim it’s “documented in code.” Simply tell it how it is: “We have no specification.”
