Re: SVN type concerns

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
this:

    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
hand.

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.

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/