Re: type names (was Re: Child package: private type and IO)

["John G. Volan" <johnv@ac3i.dseg.ti.com>]

Brian Rogoff wrote:
> 
> Amazing how much this naming style issue comes up here :-).

Indeed. :-) 

> FWIW, using the plural package name style I would probably chose either
> 
>         Employees : Linked_Lists.List_Type;
> 
> or
> 
>         Employees : Linked_Lists.List_T;
> 
> which may still be just as ugly (at least to Matthew) but makes clear
> which part of the name is the type name, even in the presence of a
> use clause. 

This scheme still doesn't give Ada programmers enough to go on to deal
with most real-world programming situations.  For instance, it seems to
me that there might be other sorts of lists in this program other than
just lists of employees (for instance, lists of companies), so it would
be unwise to use "List_Type" and "Linked_Lists" for a type and package
that only support lists of employees. And the same program might very
well make use of other kinds of employee collections than just employee
lists (for instance, employee sets or employee queues), so to name a
given variable simply "Employees", without conveying whether it is a
list or set or queue of employees, is also unwise. Besides, "Employees"
might already be the name of a package containing a type called
"Employee_Type".

I would favor the following convention:

    Employee_List  : Employee_Lists.Employee_List_Type; --*see footnote
    Employee_Set   : Employee_Sets.Employee_Set_Type;
    Employee_Queue : Employee_Queues.Employee_Queue_Type;
    Company_List   : Company_Lists.Company_List_Type;
    Company_Set    : Company_Sets.Company_Set_Type;

If you choose to use "use" (I'm not necessarily endorsing that), then
this becomes:

    Employee_List  : Employee_List_Type;
    Employee_Set   : Employee_Set_Type;
    Employee_Queue : Employee_Queue_Type;
    Company_List   : Company_List_Type;
    Company_Set    : Company_Set_Type;

In other words, be "semantically economical" when it comes to naming
things: An Ada type, its enclosing package, and all its instance
objects, can all be seen as just different manifestations of a single
abstract concept. So if you already have a pithy phrase that neatly
describes that abstraction (e.g., "employee list") then you shouldn't
waste time hunting for synonymous (and possibly less apt) phrases, just
for the sake of differentiating these various constructs. Instead, just
embed the same pithy phrase in the names of each of these constructs,
but find some systematic scheme for "marking" these names to
differentiate them. The more mechanical that sceme is, the better,
because it means less mental work for the programmer (and for the
readers!)  For instance (as demonstrated above):

(1) Mark the package name by using the plural: e.g. "Employee_Lists".

(2) Mark the type name by appending the suffix "_Type": e.g.
"Employee_List_Type".  (Or you could use "_T" if you must; the important
thing is to use your chosen marker consistently.)

(3) Reserve the unmarked form for an object name: e.g. "Employee_List". 
Use this whenever you're in a context where there's no compelling need
to distinguish that particular object from any other instance of that
type. Usually this means the object is the only instance of that type in
that context; often, this is a parameter to a subprogram.

(4) When there is a compelling reason to distinguish particular objects
(e.g., when you're dealing with more than one instance of the same type
in the same context), mark the object names by attaching adjectives that
are appropriate to the particular situation: e.g.,
"Active_Employee_List" versus "Terminated_Employee_List".

Note that most object-oriented languages make it somewhat easier than
Ada to establish a systematic, semantically-economical naming scheme,
for two reasons: (1) The "class" construct merges the roles of both a
package and a type, so there are fewer things to name.  (2) Other
languages tend to be case-sensitive, so capitalization is available as a
mechanism for "marking". For instance, instead of having to say:

    Employee_List : Employee_Lists.Employee_List_Type;

in Eiffel you could simply say:

    employeeList : EmployeeList;

and in Java or C++ this would be:

    EmployeeList employeeList;

where "EmployeeList" is the name of a class (=package+type) and
"employeeList" is the name of an object. The convention of marking class
names with initial uppercase and object names with initial lowercase
(and separating words by capitalization rather than underscores) is
well-accepted among folks using Smalltalk, C++, Java and Eiffel, so it's
become something of an industry standard.  

(Personally, after working in Java for several months, I've gotten to
like this convention. Now I find myself wishing Ada95 had gone the
case-sensitive route too... Oops! I can see another religious can of
worms opening up again... :-)

*Footnote:

The above scheme didn't consider the effect of using generics. For
example, suppose you have a generic package for linked lists:

    generic
      type Item_Type is private;
    package Lists is
      type List_Type is ...
      ...
    end Lists;

And suppose you instantiate this for different item types:

    package Employee_Lists is 
      new Lists (Item_Type => Employees.Employee_Type);
    package Company_Lists is
      new Lists (Item_Type => Companies.Company_Type);

Then what you'd have to say is:

    Employee_List : Employee_Lists.List_Type;
    Company_List  : Company_Lists.List_Type;

And you'd be forced to qualify the type names here, even if you used
"use".  

Unfortunately, when you instantiate a generic in Ada, you only get a new
package name; you don't get a new *type* name as well.  On the other
hand, in class-based OO languages that support generic templates, this
issue doesn't come up, because class=package+type. For instance, in C++,
you could have:

    typedef List<Employee> EmployeeList;
    typedef List<Company>  CompanyList;
    ...
    EmployeeList employeeList;
    CompanyList  companyList;

(When they get around to putting generic templates into Java, I
anticipate the situation will be similar.)

-- 
Signature volanSignature = 
  new Signature
  ( /*name:      */ "John G. Volan",
    /*employer:  */ "Raytheon Advanced C3I Systems, San Jose",
    /*workEmail: */ "johnv@ac3i.dseg.ti.com",
    /*homeEmail: */ "johnvolan@sprintmail.com",
    /*resumeBlip:*/ "Sun Certified Java Programmer",
    /*twoCents:  */ "Java would be even cooler with Ada95's " +
                    "generics, enumerated types, function types, " +
                    "named parameter passing, etc...",
    /*disclaimer:*/ "These views not packaged in COM.ti.dseg.ac3i, " +
                    "so loading them throws DontQuoteMeError. :-)" );