Boost logo

Boost :

From: williamkempf_at_[hidden]
Date: 2001-09-26 16:35:56


--- In boost_at_y..., "Scott McCaskill" <scott_at_m...> wrote:
> > > > * 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.

With out tacking on _one to a name, there is no name that conveys a
one to one realationship in this case. So signal_one() and broadcast
() instead. Seems like too much of an attempt to clarify things here
to me. Regardless, this ignores the historic inertia.

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

More readable to whom? To a non-newbie signal() and broadcast() are
extremely readable and understandable. That's part of the point
about historic inertia.
 
> >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.

This is where the second part about the point of historic inertia
comes in, and you failed to see it in what I said. So I'll try to
elaborate. Nearly all literature on this concept is going to use the
terms signal() and broadcast(). This is the abstract part. If the
library, the physical part, uses notify_one() and notify_all() then
there's a point of contention between the abstract and the physical
which creates understandability problems for the newbie.

This is also a problem for the expert. The expert is going to be
very familiar with the names signal() and broadcast() because of the
historical inertia and will find the attempt to switch to different
names is vexing, at least for a period of adjustment. I implemented
Boost.Threads and have used the new names a lot because of this, and
I still find my mind thinking either signal() or broadcast() and my
fingers starting to type these names.

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

I disagree totally about the relevance here. Boost can't hope to
document this very complex subject to any extent that will be truly
useful for a newbie. He might be able to crank out a few things
based on this cursory level, but he'll quickly find himself in the
need of deeper understanding and when he turns to standard literature
on the topic he'll find there's a disconnect because of the differing
names.
 
> 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.

Equating different names is not necessarily easy. And when the
concept is complex enough *ANY* additional complexity, no matter how
slight, can be a major hinderance to comprehension.

Bill Kempf


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk