[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: SVN type concerns

From: Greg Stein <gstein_at_lyra.org>
Date: 2001-02-23 06:00:07 CET

On Thu, Feb 22, 2001 at 01:34:18PM -0600, Karl Fogel wrote:
> I definitely find that svn_boolean_t makes code more readable for me;
> I think cmpilato and a few others feel the same way.

This is because you see "int" and wonder about the domain of legal values.
Can you use -3? How about 42?

If you see svn_boolean_t or bool or boolean, you *know* the domain is
comprised of 0 and 1. Anything else is "illegal".

On the other side of the boolean wall, when you see a function used like

    call_some_func ("your mom", "your brother", "don't want to know", 1);

What the hell does that 1 mean? What if I passed 7?

If the last line said TRUE, then I know it is representing a boolean value.

Sure, sure... "documentation saves all". Not when you're reading through
pages of code. Relying on the doc to pull yourself out of this situation is
a bit scary. Want an excellent example case? Consider the other day when Jim
put -1 into the code. Sure, the doc *over in that file there* said what the
hell it meant, but I wasn't reading that file. I just saw -1 and wondered
WTF that meant. Using a symbol such as SVN_FS__UNUSED_REVNUM would have been
immediately obvious.

TRUE and FALSE play the same game: *local* documentation for the task at

svn_boolean_t is great for documenting the constraints of the particular
lvalue. TRUE/FALSE are great for documenting how a particular value is going
to be interpreted.

Documentation *elsewhere* can be helpful, but should never be considered the
sole source. Local doc is always an improvement.

Note that the use of svn_boolean_t and svn_revnum_t are analogous. Local doc
about a particular type: its meaning, its domain, where it can be passed
around (e.g. you don't pass an svn_revnum_t to a func taking a long int:
there is probably a mistake somewhere (possibly as mundane as a mistype on
the func decl)). TRUE and SVN_INVALID_REVNUM are also analogous.


Greg Stein, http://www.lyra.org/
Received on Sat Oct 21 14:36:23 2006

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.