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.
| 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. | |  | |
This entry was posted
on Thursday, 18th March, 2010.
You can follow any responses to this entry through the RSS 2.0 feed.
You can leave a response, or trackback from your own site.
Possibly related posts
Reference implementations, HTTP textures, Iterations
Commenters are to be civil, courteous and respectful to others, insofar as it is possible to do so. Beyond that, you're not required to agree with the opinions expressed by me or by others.
Think for yourselves! First time commenters will wind-up in the moderation queue and your comment won't appear right away. Ditto for anything that gets flagged by the anti-spam rules.
I don’t disagree with the need to document code especially when it concerns protocol/api interactions (and especially if it concerns money *smiles*)
However, on some front end/UI features it’s challenging to document all expected functionality, because that can change rapidly with usability feedback and A/B testing. Having to document different variants over and over as features get tweaked (often daily) can slow things down. Or put another way, having a lightweight way of documenting expected behavior or a feature, either as code comments or spreadsheet with revisioning, or other often can be more efficient. of course this doesn’t apply to mission critical systems like medical appliances, ABS system etc
Documentation is certainly a process, and a living one at that. My teams always worked with detailed documentation, which was kept up-to-date throughout development. If we needed more manpower, or someone got sick, we could always bulk up and have someone writing productive code on just a couple hours’ notice, without slowing the rest of the team.
It’s the one way I know to add manpower to a project without making the project run even later.
Marshall McLuhan is a media studies researcher, dammit, not a software engineer pundit x(
“The Medium Is The Message”, but “The Code Is NOT The Documentation”, right?
The medium is only occasionally the message
was this article a response to that part in the TPV policy that says somthing along the lines of “your viewer must be compatible with the official protocol as documented in our source code” ?
That sentence was one of the things I had in mind, certainly
When I read this article, the whole Microsoft/European Commission battle a few years ago over their poor interoperability protocol documentation(specifically SMB/CIFS) comes to mind as another example of the dangers of code as protocol documentation.
In regards to the TPV policy, having the code as protocol documentation is an invitation to copyright infringement by projects that aren’t licensed under the same terms as LL’s viewer code. As a potential example, the Radegast viewer is BSD-licensed and a spot of GPL code might slip in due to “code as documentation”. Of course whatever infringement there might be is purely unintentional and no malice intended, but because of LL’s failure to provide proper protocol documentation it’s practically unavoidable, unless you play the very harsh game of reverse-engineering.
There does seem to be something in the way of protocol documentation available, but it doesn’t seem complete enough: http://wiki.secondlife.com/wiki/Protocol and http://wiki.secondlife.com/wiki/Documentation