Keeping Code Readable with Ada Generics

In my last blog post on Ada renames I re-iterated the commonly accepted guideline within the Ada community that language features such as use clauses, renames and overloading should be avoided so that traceability to packages will be retained within code. There are however some circumstances where these principles may be relaxed. Renames, as I previously described, is one case (ADA Renames); another occurs with generic subprograms and packages.

Within this post I will suggest a few coding techniques which utilise some of these “less approved” language features when working with generics. The aim however is still to retain clarity and traceability.

Consider the following example; we have a simple subprogram to swap a pair of integers:

   procedure Swap ( Item1, Item2 : in out Integer) is
      Temp : Integer;
   begin
      Temp  := Item1;
      Item1 := Item2;
      Item2 := Temp;
   end;

Having discovered that we also need to do the operation for floating point we convert this to a generic procedure:

generic
      type Item_T is private;
   procedure g_Swap ( Item1, Item2 : in out Item_T);
   
   procedure g_Swap ( Item1, Item2 : in out Item_T) is
      Temp : Item_T;
   begin
      Temp  := Item1;
      Item1 := Item2;
      Item2 := Temp;
   end;

How should we instantiate this item – like this?

procedure SwapIntegers is new g_Swap (Item_T => Integer);
procedure SwapFloats is new g_Swap (Item_T => Float);

This would appear to fit in with our principal of traceability, however if you consider the functionality is generic function, in this case a clearer code construct can be achieved by overloading the instances, i.e.

procedure Swap is new g_Swap (Item_T => Integer);
procedure Swap is new g_Swap (Item_T => Float);

So when we write the code, regardless of the item types, we just write:

Swap(Item1, Item2);

and if we find a new type which requires this operation we just instantiate a new instance of the underlying generic as swap. A useful suggestion here is that all these instantiations are declared contiguously, making it obvious that all the operations are effectively identical. This can be considered as analogous to the standard operators - + - * / etc. We know what they do and are less concerned about where they are derived.

How do we approach generic packages? Consider the following example:

generic
    Size  : Positive; 
    type Element_T is private;
package g_Stack is
    StackOverflow : exception;
    StackeEmpty   : exception;
    procedure Push (E: Element_T);
    function  Pop return Element_T;
end g_Stack;

We cannot overload the instances of the package so we are forced to implement:

package I_Stack is new g_Stack(Size=> 100, Element_T=> Integer);
package F_Stack is new g_Stack(Size=> 100, Element_T => Float);

The only solution here is the use clause; this does not in this instance significantly reduce traceability as we would normally create the new instances of the generics in the same place we are declaring local subprograms. These are not external packages but locally declared items.

A good example of the improvement in code clarity is given in the following example. This uses several of the Ada.Text_IO generic sub packages. These have many identically named subprograms. Thus a final example fragment contains a procedure to convert a light wavelength in nanometers to a perceived colour:

with Ada.Text_IO;
package example is
   min_visible : constant := 380.0;
   max_visible : constant := 750.0;

   type Colour_T is (VIOLET,BLUE,GREEN,YELLOW,ORANGE,RED);
   
   RainBow : array (Colour_T) of float := 
--   VIOLET, BLUE,   GREEN,  YELLOW, ORANGE, RED
      (  450.0,  495.0,  570.0,  590.0,  620.0,  750.0  );

   package My_F_IO is new Ada.Text_IO.Float_IO(Num => Float);
   package My_C_IO is new Ada.Text_IO.Enumeration_IO(Colour_T);
   use My_F_IO; use My_C_IO; use Ada.Text_IO;

procedure ToColour (Wavelength : in FLOAT) is
begin
   if Wavelength > max_visible or Wavelength < min_visible
   then
      Put ("Wavelength "); Put (Wavelength); Put_Line ( " not visible");
   else
PrintColour:
      for Colour in Colour_T loop
         if Wavelength <= Rainbow(Colour)
         then
            Put("Wavelength "); Put(Wavelength); Put(" is "); Put(Colour);
            New_Line;
            exit PrintColour;
         end if;
      end loop PrintColour;
   end if;
end ToColour;

Consider the line:

Put("Wavelength "); Put(Wavelength); Put(" is "); Put(Colour); New_Line;

This uses three different overloaded instances of the Text_IO subprogram Put. It is obvious to even the most casual reader where these are derived and no useful purpose would be served by:

Ada.Text_IO.Put("Wavelength "); 
My_F_IO.Put(Wavelength); 
Ada.Text_IO.Put(" is ");
My_C_IO.Put(Colour);
Ada.Text_IO.New_Line;

This example shows that judicious use of overloading and the use clause – as with renaming – can be used to enhance the clarity of the code without significantly impacting traceability. This can even simplify the coding process, allowing implementers to concentrate on other more important considerations.

These are not hard and fast rules – implementation should always consider all aspects of code clarity and traceability. In some instances it may be considered better to avoid the techniques detailed above, but in other cases these suggestions may noticeably simplify the implementation with no detrimental effect. The only real rule is that rules are usually there for a good reason, but in some cases it is better to consider the reason for the rule and perhaps take an alternative approach.