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
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:
- 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.
- 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
Posted by bzbarsky at 12:07 AM