Re: Naming of Tagged Types and Associated Packages

["John G. Volan" <johnvolan@sprintmail.com>]

[Apologies if this turns out to be a re-post. Having some problems with
my newsfeed...]

Matthew Heaney wrote:
> 
> "John G. Volan" <johnvolan@sprintmail.com> writes:
> 
> > > I do this sort of thing too:
> > >
> > >    PDW : Pulse_Descriptor_Word;
> > >
> > >    SOI : Signal_Of_Interest;
> >
> > I thought one assumption in this discussion was that we were trying to find
> > schemes that would allow us to avoid abbreviations.  But if abbreviations
> > were fair game, then there would never have been an issue:
> 
> Those happen to be the terms people on our project really use to refer
> to the entity.  "What was the value of the pee dee double-yew?"  "What's
> the ess oh eye?"

Abbreviations per se are not evil. If an abbreviation or acronym is
well-known and well-established in a given problem domain (e.g. your PDW
or SOI), then it's a legitimate candidate for the name of a program
entity.  

Rather, it's _ad-hoc_ abbreviations that are evil, abbreviations that a
programmer invents on the spot for his own convenience but without any
basis from the problem domain.  (For instance, your "FMode" and "OMode"
for "File_Mode" and "Operational_Mode", when you were forced to
disambiguate "Mode" in a specific context.)

But if well-established abbreviations like PDW and SOI are good names,
then they're good not just as variable names, but also as type names --
and we're back to square one!

The problem with using a legitimate abbreviation like SOI _and_ the
fully-spelled out term Signal_Of_Interest within the same program is
that these verge on being synonyms of each other, and this might be
construed as a violation of the "No Synonyms" principle. (Whether you
want to subscribe to that principle, is of course up to you.) What this
principle seeks to avoid is situations like this:

    Position : Location;
    Direction : Azimuth;
    Point : Vertex;

It would be better either to have:

    Position : Position_Type;
    Direction : Direction_Type;
    Point : Point_Type;

or this would be okay:

    Location : Location_Type;
    Azimuth : Azimuth_Type;
    Vertex : Vertex_Type;

In other words, for each concept from your problem domain, use just one
term for it in your program text.

According to that principle, the following would be okay:

    PDW : PDW_Type;
    SOI : SOI_Type;
    -- as long as these acronyms were documented in the official
    -- project acronym list and the programmers were trained

or this would be okay:

    Pulse_Descriptor_Word : Pulse_Descriptor_Word_Type;
    Signal_Of_Interest    : Signal_Of_Interest_Type;

but NOT this:

    PDW : Pulse_Descriptor_Word;
    SOI : Signal_Of_Interest;

Of course, that's a pretty strict reading of the No Synonyms principle.
Is an acronym _really_ a distinct synonym for the spelled-out term?  One
could argue that it's just an alternate _form_ for that term, so why not
allow both? 

The problem is that this is a slippery slope. If programmers start out
with supposedly legitimate cases like "SOI: Signal_Of_Interest" and get
used to that as a pattern, it's just too tempting to slide into ad-hoc
cases like "FM: File_Mode" when the going gets tough.

How do you tell an ad-hoc abbreviation from a legitimate one?  If you
see a given abbreviation on a page, what feature of it will leap out and
tell you whether it's in the approved list or it's something the
programmer made up on the spot?  The answer is, nothing.  Unless you're
an extreme expert on the problem domain (and not all programmers are),
you'd need to go check the list.

Another argument against cases like "SOI: Signal_Of_Interest" is this:
If "SOI" and "Signal_Of_Interest" are just two equally-good forms of the
same term, then why not give the programmer the discretion to choose
_either_ form, anyplace where that term comes up in the program?  In
other words:

    type Signal_Of_Interest_Type is ... ;
    subtype SOI_Type is Signal_Of_Interest_Type;
      -- using a subtype as a "renaming" for a type

And then let each programmer choose either to use

    SOI : SOI_Type;

or to use

    Signal_Of_Interest : Signal_Of_Interest_Type;

at their own discretion.  

Another way of putting it is: Why lock up the spell-out form of a term
like "Signal_Of_Interest" as a type name?  That prevents programmers
from using it as a variable name when they want to.  You're essentially
_forcing_ them to use the abbreviation when they want to name their variables.

-- 
indexing
   description: "Signatures for John G. Volan"
   self_plug: "Ex Ada guru", "Java 1.1 Certified", "Eiffelist wannabe"
   two_cents: "Java would be even cooler with Eiffel's assertions/DBC, %
              %generics, true MI, feature adaptation, uniform access, %
              %selective export, expanded types, etc., etc..."
class JOHN_VOLAN_SIGNATURE inherit SIGNATURE invariant
   disclaimer: not (opinion implies employer.opinion)
end -- class JOHN_VOLAN_SIGNATURE