Three Monkeys, Three Typewriters, Two Days

Interface writing and how NOT to do it

Consider the initial checkin of the tree box object interface. Note the complete lack of useful documentation. Try to figure out what to pass to the getCellAt() method. Just try. But it's OK because it's not part of build, right? Or so the thinking seems to go.

That interface, and many others like it, have survived more or less in this exact state until now. Implementations are broken because people didn't know what to implement; callers are broken because they couldn't tell what to pass. Things get passed based on trial and error; sometimes they work due to hacks in the callers or implementations, sometimes they do not.

So I've resolved two things:

1. I will try, to the utmost of my ability, to make sure code like this either doesn't land at all (not even "not part of build") or at least is not allowed to be enabled in the default build until the interfaces are documented. If people want it on badly, that's great—that means they have lots of incentive to document.
2. I will try, again to the utmost of my ability, not to try to cause bodily harm to people who checked in code like this in the past, if and when I actually meet them. I can't offer any guarantees on this front, though. Having several days of my life completely eaten up because they were too lazy to spend half an hour documenting their interface does not make me a happy camper.