6 Subprograms

6.1 Subprogram Declarations

• Do not write the in for parameters.

        function Length (S : String) return Integer;
  

• When the declaration line for a procedure or a function is too long to fit the entire declaration (including the keyword procedure or function) on a single line, then fold it, putting a single parameter on a line, aligning the colons, as in:

       procedure Set_Heading
         (Source : String;
          Count  : Natural;
          Pad    : Character := Space;
          Fill   : Boolean   := True);
  

  In the case of a function, if the entire spec does not fit on one line, then the return may appear after the last parameter, as in:

        function Head
          (Source : String;
           Count  : Natural;
           Pad    : Character := Space) return String;
  

  Or it may appear on its own as a separate line. This form is preferred when putting the return on the same line as the last parameter would result in an overlong line. The return type may optionally be aligned with the types of the parameters (usually we do this aligning if it results only in a small number of extra spaces, and otherwise we don’t attempt to align). So two alternative forms for the above spec are:

        function Head
          (Source : String;
           Count  : Natural;
           Pad    : Character := Space)
           return   String;
  
        function Head
          (Source : String;
           Count  : Natural;
           Pad    : Character := Space)
           return String;
  

6.2 Subprogram Bodies

• Function and procedure bodies should usually be sorted alphabetically. Do not attempt to sort them in some logical order by functionality. For a sequence of subprogram specs, a general alphabetical sorting is also usually appropriate, but occasionally it makes sense to group by major function, with appropriate headers.
• All subprograms have a header giving the function name, with the following format:

        -----------------
        -- My_Function --
        -----------------
  
        procedure My_Function is
        begin
          ...
        end My_Function;
  

  Note that the name in the header is preceded by a single space, not two spaces as for other comments. These headers are used on nested subprograms as well as outer level subprograms. They may also be used as headers for sections of comments, or collections of declarations that are related.

• Every subprogram body must have a preceding subprogram_declaration, which includes proper client documentation so that you do not need to read the subprogram body in order to understand what the subprogram does and how to call it. All subprograms should be documented, without exceptions.
• A sequence of declarations may optionally be separated from the following begin by a blank line. Just as we optionally allow blank lines in general between declarations, this blank line should be present only if it improves readability. Generally we avoid this blank line if the declarative part is small (one or two lines) and the body has no blank lines, and we include it if the declarative part is long or if the body has blank lines.
• If the declarations in a subprogram contain at least one nested subprogram body, then just before the begin of the enclosing subprogram, there is a comment line and a blank line:

      --  Start of processing for Enclosing_Subprogram
  
      begin
        ...
      end Enclosing_Subprogram;
  

• When nested subprograms are present, variables that are referenced by any nested subprogram should precede the nested subprogram specs. For variables that are not referenced by nested procedures, the declarations can either also be before any of the nested subprogram specs (this is the old style, more generally used). Or then can come just before the begin, with a header. The following example shows the two possible styles:

      procedure Style1 is
         Var_Referenced_In_Nested      : Integer;
         Var_Referenced_Only_In_Style1 : Integer;
  
         proc Nested;
         --  Comments ...
  
  
         ------------
         -- Nested --
         ------------
  
         procedure Nested is
         begin
            ...
         end Nested;
  
      --  Start of processing for Style1
  
      begin
         ...
      end Style1;
  
  

      procedure Style2 is
         Var_Referenced_In_Nested : Integer;
  
         proc Nested;
         --  Comments ...
  
         ------------
         -- Nested --
         ------------
  
         procedure Nested is
         begin
            ...
         end Nested;
  
         --  Local variables
  
         Var_Referenced_Only_In_Style2 : Integer;
  
      --  Start of processing for Style2
  
      begin
         ...
      end Style2;
  
  

  For new code, we generally prefer Style2, but we do not insist on modifying all legacy occurrences of Style1, which is still much more common in the sources.