Ada 95 Quality and Style Guide Chapter 3

Chapter 3: Readability - TOC - 3.2 NAMING CONVENTIONS

3.2.2 Subtype Names

guideline

  • Use singular, general nouns as subtype identifiers.
  • Choose identifiers that describe one of the subtype's values.
  • Consider using suffixes for subtype identifiers that define visible access types, visible subranges, or visible array types.
  • For private types, do not use identifier constructions (e.g., suffixes) that are unique to subtype identifiers.
  • Do not use the subtype names from predefined packages.

  • example
    type Day is
       (Monday,    Tuesday,   Wednesday, Thursday,  Friday,
        Saturday,  Sunday);
    type Day_Of_Month    is range      0 ..    31;
    type Month_Number    is range      1 ..    12;
    type Historical_Year is range -6_000 .. 2_500;
    type Date is
       record
          Day   : Day_Of_Month;
          Month : Month_Number;
          Year  : Historical_Year;
       end record;
    

    In particular, Day should be used in preference to Days or Day_Type.

    The identifier Historical_Year might appear to be specific, but it is actually general, with the adjective historical describing the range constraint:

    ------------------------------------------------------------------------
    procedure Disk_Driver is
       -- In this procedure, a number of important disk parameters are
       -- linked.
       Number_Of_Sectors  : constant :=     4;
       Number_Of_Tracks   : constant :=   200;
       Number_Of_Surfaces : constant :=    18;
       Sector_Capacity    : constant := 4_096;
       Track_Capacity   : constant := Number_Of_Sectors  * Sector_Capacity;
       Surface_Capacity : constant := Number_Of_Tracks   * Track_Capacity;
       Disk_Capacity    : constant := Number_Of_Surfaces * Surface_Capacity;
       type Sector_Range  is range 1 .. Number_Of_Sectors;
       type Track_Range   is range 1 .. Number_Of_Tracks;
       type Surface_Range is range 1 .. Number_Of_Surfaces;
       type Track_Map   is array (Sector_Range)  of ...;
       type Surface_Map is array (Track_Range)   of Track_Map;
       type Disk_Map    is array (Surface_Range) of Surface_Map;
    begin  -- Disk_Driver
       ...
    end Disk_Driver;
    ------------------------------------------------------------------------
    

    The suffixes _Capacity, _Range, and_Map help define the purpose of the above subtypes and avoid the search for synonyms for the sector, track, and surface abstractions. Without the suffixes, you would need three different names per abstraction, one to describe each of the concepts succinctly named in the suffix. This recommendation only applies to certain visible subtypes. Private types, for example, should be given a good name that reflects the abstraction being represented.

    rationale

    When this style and the suggested style for object identifiers are used, program code more closely resembles English (see Guideline 3.2.3). Furthermore, this style is consistent with the names of the language's predefined identifiers. They are not named Integers, Booleans, Integer_Type, or Boolean_Type.

    However, using the name of a subtype from the predefined packages is sure to confuse a programmer when that subtype appears somewhere without a package qualification.

    notes

    This style guide tries to be consistent with the Ada Reference Manual (1995) in use of the terms "type" and "subtype" name. In general, a "type" refers to the abstract concept, as in a type declaration, while the "subtype" refers to the name given to that abstract concept in an actual declaration. Thus, what was called a type name in Ada 83 (Ada Reference Manual 1983) is now called a subtype name.


    < Previous Page Search Contents Index Next Page >
    1 2 3 4 5 6 7 8 9 10 11
    TOC TOC TOC TOC TOC TOC TOC TOC TOC TOC TOC
    Appendix References Bibliography