🚀 go-pugleaf

Hmm.  Interesting topic, inevitably flame-prone.  I'm inclined away from the
`name includes type name' approach *but* under conditions like the following:

At any given point in a piece of code (roughly, in any given block), I don't
like seeing more than a few names (and that does include function names)
*active* (as opposed to `in scope').  A handful whose scope isn't fairly local;
plus maybe a dozen (on a busy day) whose declaration is visible on the same page
as the piece of code.  I want the naming convention to make obvious which ones
are the aliens; and the naming conventions for the aliens had better say a lot
about their nature.  I'd be happy with the type being apparent from the name in
these cases.  For the local variables of a block I *do*not* want the name
cluttered with the type.  The declaration's visible and I want the reader to
*notice* it; aside from anything else, its information content goes beyond type
and name; specifically, there's information in *where* it's declared (scope) and
the comment next to it.

Roughly speaking, I want to work in a spectrum: one extreme is a global symbol,
whose declaration I can't see.  I want its name to tell me where to look for its
declaration; telling me its type doesn't sound a bad idea either.  Telling me
its use is indispensable.  At the other extreme, there's that idiotic variable
which is just holding a value for the duration of a swap.  It's in scope for two
lines.  Call it swap or swapper (but, please, not temp and NEVER `i'). Between
these two extremes, the more local you get the less info (aside from purpose) I
want in the name; but it's *use* never ceases being important.

Turning around another way, though, I've looked at the fragments used in
illustrations and one thing leaps out of the page at me.  Just as an object's
name must express the purpose of the object, the name of a type must give an
outsider at least some idea of _its_ purpose; `HWND' says precisely nothing to
me.  I think, if I had to work with a library which used such horrible names for
its types I'd have a standard header imported by my code which cheerfully does
typedef HWND WindowHandle; /* documentation for the type */
so that, at least, my code would have some chance at being readable.  Possibly
followed by a set of macros
#define WindowWidth(WinHan) ((WinHan)->wsz0)
if the fieldnames in HWND are as unhelpful as the name itself.  If I wasn't
adding enough code to make it worth such definitions, I'd name my variables so
that their names tell readers what they are and I wouldn't want the dumb
typename present in those names.  Is there really something out there which uses
type names like HWND, lpszString ? (And, BTW, why wasn't that hypothetical
declaration `LPSZString lpszString;' ?  If there's a type implemented as char *
with some abstract meaning (even if it's just String) give it a name which
expresses that meaning and declare objects of that type by the type name, not by
the implementation; especially if there's several types with one implementation
but distinct abstract meanings.  Even if you can't possibly ever be going to
change the implementation of that type, the abstraction makes code clearer for
the reader.)

A naming convention is important.  I want every name to tell me the purpose of
the thing it names; often this _will_ involve indicating its type.  For things
whose declaration I can't see, I want the name to indicate where to look to find
its declaration and documentation.  At a lower priority than either of these, I
think there is a time and a place for including the name of its type in the name
of a symbol; but this will be a total waste of time if the types are named
without thought for the reader; in particular, if the type name isn't subject
to the rules of a naming convention.

I remain skeptical of gaining from the things its possible to get an automatic
system to do.  Maybe I've just had bad experiences from the `Total Quality'
approach which attempts to get quality by imposing rules when the real priority
can't be addressed except by intelligent (and cooperative) practice.  The best 
such rules can do is fail to forbid the intelligent practice; few manage this.

	Eddy.
--
				...   Few indeed are those who, travelling
it, have crossed the dark and yawning Abyss of Implementation to Delivery.
Many, yea, many in truth stagnate yet in the Desert of Delay, or linger ever
in the ghastly limbo called Perpetual Beta.	(from the LOGINATAKA)