Comments on: Implementation isn’t documentation

By: Antonius Misfit

Antonius Misfit — Mon, 05 Apr 2010 00:20:49 +0000

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

By: Tateru Nino

Tateru Nino — Sun, 21 Mar 2010 04:55:59 +0000

That sentence was one of the things I had in mind, certainly

By: TigroSpottystripes Katsu

TigroSpottystripes Katsu — Sat, 20 Mar 2010 21:05:40 +0000

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” ?

By: Tateru Nino

Tateru Nino — Sat, 20 Mar 2010 14:57:39 +0000

The medium is only occasionally the message

By: Patchouli Woollahra

Patchouli Woollahra — Sat, 20 Mar 2010 14:42:28 +0000

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?

By: Tateru Nino

Tateru Nino — Thu, 18 Mar 2010 11:35:27 +0000

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.

By: Simon Newstead

Simon Newstead — Thu, 18 Mar 2010 11:20:12 +0000

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