[cairo] A gentle request for better commit messages

[Ian Osgood]

On Sep 18, 2008, at 9:44 AM, Carl Worth wrote:
>
> -Carl
>
> [**] It's worth noting that we've got a nice demonstration here of the
> problems that happen with Boolean parameters to functions. It's far  
> too
> easy to make a mistake like this and far too hard to notice it by just
> examining the code. Note also that even if these two Booleans were
> replaced with some symbolic constants, (our usual solution for Boolean
> parameters), the compiler would still silently let the swap go by. So
> that wouldn't have prevented this bug. But then we would at least  
> have a
> chance of some static analysis tool catching the problem and  
> alerting us
> of it. And, of course, the symbolic constants would make the intent of
> the code much more obvious from just reading it, (perhaps making it
> easier for me to guess the impact of this bug from just reading this
> diff).

I completely agree. At previous jobs I'd seen some highly devolved  
internal APIs which festered strings of four or more boolean  
parameters in a row. Boolean parameters are one of those creeping  
features that are best to avoid:

1. A "flags" parameter with symbolic mask values which may be ORed  
together is easier to read and to extend without breaking ABI.

2. Sometimes the intent of a boolean parameter is better expressed  
with two different function names. The two functions may then contain  
small amounts of specific code before calling a common function.

Apple, perhaps the best API designer in the world, was the place I  
saw these patterns applied most consistently.

Ian