Re: [boost] Re: Review: Boost.Threads

From: Scott McCaskill (scott_at_[hidden])
Date: 2001-09-26 15:48:59

> > > * Q: notify_* readable by non-experts, signal/broadcast not?
> > >
> > > A:
> > >
> > > It is a feature that signal/broadcast are unreadable by non-
> experts. This
> > > causes an immediate task-switch to documentation reading mode.
> > >
> >
> > That borders on intentional obfuscation.  Classes and methods
> should be
> > named according to what they are or what they do, respectively.
>
> And both signal() and broadcast() are meaningful for what is done.

broadcast is ok, signal is not.  As I explained earlier, the meaning of the
word signal does NOT connotate a one-to-one relationship between signaller
and signalled, and for that reason it is a poor counterpart to broadcast.

> Not as intuitive as the others for newbies, but I find this argument
> less compelling then the inertia of historic usage.

This is not merely about making things easier for newbies.  The names of
these methods will be of marginal assistance (or hinderance) at best in
aiding a newbie in understanding the concepts behind the names.  Rather,
this is about making code more readable via the use of mnemonic names.

>Again, I can't
> state this enough.  Newbies should *NOT* be attempting to learn how
> to write MT programs by looking at MT code.  It's just too
> dangerous.

I agree that they shouldn't learn ONLY by looking at code.. but looking at a
well written sample program is definitely an important part of learning
about MT programming.  It's rarely sufficient to learn about these concepts
in the abstract; that's a large part of the value of the sample programs.

> Threading is a complex and error prone way of
> programming, no matter how intuitive the idea of it is, or how
> intuitive the interface names are.  And when these newbies go to look
> at the literature they will find it confusing that everyone else uses
> terminology that we don't use in Boost.Threads.
>
> > > notify_one/notify_all are readable enough that a non-expert would
> be
> > tempted
> > > to _not_ check what their precise semantics are - and get burned.
> > >
> >
> > One could make that argument for any well-named, non-trivial
> function.  API
> > names are meant to be mnemonic, not substitues for documentation.
>
> Exactly, and the vast library of documentation on the concepts (as
> opposed to the Boost.Threads library and it's documentation) will use
> the names signal() and broadcast().
>

Firstly, I don't think it's a given that most newbies will go out and read a
lot of other literature about condition variables.  Sure, some will--but I
think a lot of people will rely largely on the boost documentation and the
sample programs.  The extent to which this is desireable or undesireable is
not relevant.

Secondly, equating different names is relatively easy, and the differences
can even provide some additional insight into the underlying concepts.  It's
getting a solid understanding of the underlying concepts that is
challenging, regardless of the names.  Given this, I see no reason to settle
for names that are less descriptive.

Scott McCaskill