On Thu, 2003-06-19 at 19:43, Christian Daudt wrote:
> it's only that I grew to a different mantra: "be liberal in what you receive
> and strict in what you send"
Unfortunately, this mantra has been used to justify some subtle, and
awful mistakes. If you try to write an RFC822 (or 2822) parser today,
you'll find that the paper standards are of limited help, because every
MUA author was "liberal in what they accepted" in arbitrary and
undocumented ways.
The more important principle is "document what you accept," whether
that's liberal or conservative. I'll give an example of a place where
we violate this principle: svn_path_uri_encode is documented as:
/** Return a URI-encoded copy of @a path, allocated in @a pool. */
>From this documentation (and the fact that PATH is a const char *),
you'd expect that PATH should be a zero-terminated C string. But it
turns out that PATH can also be NULL, in which case the function returns
NULL, due to an explicit check.
By supporting this laxity and not documenting it, the Subversion API is
placed into an uncomfortable state. Code may come to rely on this
undocumented behavior, perhaps by accident. We won't know. If
svn_path_uri_encode is ever rewritten for some reason, the author of the
new code may not notice that the old function accepted a NULL argument
and may change that behavior, breaking the code which relied on it.
As with all good principles, there are compromises to be made. The svn
editor interface documents certain restrictions on the editor call
sequence, but many editors do not enforce these restrictions. They work
just fine if you (for example) open and manipulate two sibling
directories at once. And we've run into situations where callers did
the wrong thing and got away with it until CMike noticed and fixed them,
but it would be too expensive to check and enforce the ordering
constraints in every editor. (The editor interface could be changed to
eliminate the directory handles, eliminating this problem, but there are
other examples of complex constraints which simply can't be checked.)
Nevertheless, if you've specifically gone out of your way to be lax--for
example, to write "if (path == NULL) return NULL;" in
svn_path_uri_encode, there is no excuse for not documenting this
behavior. (And one should first consider whether there is any value in
accepting NULL; would any non-broken code ever want to pass in a NULL
path?)
</treatise>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Jun 23 19:41:33 2003