An ounce of documentation is worth a pound of implementation. In conjunction with a specification (or documentation, if you prefer the more inclusive term), a reference implementation is a good thing. Without a specification, a reference implementation is an astonishingly efficient way of propagating bugs into third-party software.

The Second Life viewer is in the latter category, alas.

Allow me to illustrate. Here’s a sample function:

f(n){  return n > 0 ? n-- * f(n) : 1}

Okay, so the question is, is this function correct, or is there a bug?

“How the hell should I know?” I hear you cry, “I don’t know what it is supposed to do!

Exactly my point.

Now, in a relatively self-contained application, you might be able to figure it out from the context in which it is used, looking at the places the function is used, and how its results are applied. Likely that would lead you to realise that the function is indeed buggy. (For those of you that are wondering, it should be “n > 1”)

However, when the code is only part of a larger software eco-system, interacting with other software and services (as the Second Life viewer does), it becomes much harder to determine whether a given function is actually doing things as it ought to.

Quite a number of notable viewer bugs over the years have been the result of functions which were doing the wrong thing, but it was hard to figure out that they were doing the wrong thing because there was no indication as to what constituted correct behaviour.

That is, there was no specification to determine what was intended, only the code itself which only tells you – right or wrong – what is actually happening.

Ultimately, the process of proper debugging is a process of making the implementation conformant to the specification, rather than giving the implementation the appearance of functioning correctly. If it still doesn’t work, the specification may be wrong, but that can be corrected, and all of the disparate pieces of software built from the specification can be corrected.

In an ideal situation, a third-party has the specification for a system, and a reference implementation to work from, but really as long as an implementation is compliant with a suitably detailed specification, everything should work.

The code is not the documentation.

A reference implementation is the poorest possible excuse for documentation/specification. The implementation only tells you what is, and not what it should be. Code copied or imported from reference implementations may be just plain wrong. In that case, the reference implementation has exported a bug to third-party implementations, without any signposts towards correct behaviour that might ease the path towards fixing that bug for all implementations.

Unfortunately, this whole situation has plagued Second Life development on and off for years. Code has been produced (for the viewer, for the sims, and for assorted grid services) based on what appeared to be correct, based on code or data that itself may not have been correct. Without documentation to check code and data against, even bug-fixing can introduce more bugs than it corrects.

In the case of the sample function, what if the bug in it remained undiscovered from the assumption that the code was correct? When something misbehaved as a result, you might fix that other thing (compounding the error into other parts of the code). Glitches can be propagated outwards into the furthest reaches of an application, and nobody is the wiser, because there is nothing to compare the behaviour of the code to or to develop proper tests from.

You might write a set of unit tests that validate incorrect behaviour as easily as correct behaviour.

I personally believe that Linden Lab’s primary development priority should be the production and publication of orderly specifications and documentation. That’s to everybody’s benefit. It makes buggy code harder to write, easier to test for, and simpler to find; It helps teams working on different subsystems to smoothly coordinate without wasting each-other’s time; it supports third-party viewer development and helps third-parties find bugs in reference code. All of that in turn should vastly accelerate development and debugging.

An ounce of documentation is worth a pound of implementation.

Tags: , , , , ,

Categories: Second Life, Software.



Got a news tip or a press-release? Send it to [email protected].
Read previous post:
Close