• About us…

  • The archives

  • RSS The Gaming Session

  •  Better and faster with IPv6

  • ipv6 ready

Perhaps one of the most unfortunate situations I’ve had with a developer in the past is when one came to me and reported that a particular piece of software was ready; and when I asked for the protocol documentation, they told me that “The code is the documentation.”

That’s amateur-hour. The code isn’t the documentation, and with good reason. Recognizing the necessary difference between the two makes the difference between a coder and a software engineer.

In one sense, code is a kind of documentation, that is from specification to design to code, you are merely describing a system in increasing levels of detail, until you reach the explicit, unambiguous baby-talk grammar that a computer can use to perform the tasks you are setting it.

So, why isn’t the implementation as good as the documentation? It works doesn’t it?

Well, does it? How, exactly do you tell?

The difference between a protocol document and the code that expresses it is largely one of intent.

Documentation describes what it should do. Code describes what it actually does – even if that’s the wrong thing.

Code only describes a single, potentially correct case.

What if the protocol allows for functions, communications, features and fallbacks that you simply haven’t implemented at the present time? How would anyone know that they were available?

What if the code works differently to how the protocol should function, but it just happens to work that way at the moment?

You can poison an entire generation of software by promulgating bugs via code-as-documentation. Inevitably when someone discovers that there’s something very wrong with the code, fixing the problem can break compatibility with everything else implementing the protocol, because they are also implementing the bugs.

Protocol/standards documents set the goal. The code/implementation is an attempt to achieve that goal, and the documentation is the measure that you use to determine whether you’ve achieved it or not.

It’s specious and sloppy to assume you can implement important protocols without documentation, and folly to think you can expect third-parties to do so from your code without inviting long-term hardship or disaster for all concerned.

Got a news tip or a press-release? Send it to news@taterunino.net.
Read previous post: