Routines are composed of individual statements, data, control structures, comments— all the things discussed in the other parts of the chapter. This section provides layout guidelines unique to routines.

Use blank lines to separate parts of a routine. Use blank lines between the routine header, its data and named-constant declarations (if any), and its body.

Use standard indentation for routine arguments. The options with routine-header layout are about the same as they are in a lot of other areas of layout: no conscious layout, endline layout, or standard indentation. As in most other cases, standard indentation does better in terms of accuracy, consistency, readability, and modifiability. Example 31-62 shows two examples of routine headers with no conscious layout:

bool ReadEmployeeData(int maxEmployees,EmployeeList *employees,
   EmployeeFile *inputFile,int *employeeCount,bool *isInputError)
...

void InsertionSort(SortArray data,int firstElement,int lastElement)

These routine headers are purely utilitarian. The computer can read them as well as it can read headers in any other format, but they cause trouble for humans. Without a conscious effort to make the headers hard to read, how could they be any worse?

The second approach in routine-header layout is the endline layout, which usually works all right. Example 31-63 shows the same routine headers reformatted:

bool ReadEmployeeData( int             maxEmployees,
                       EmployeeList    *employees,
                       EmployeeFile    *inputFile,
                       int             *employeeCount,
                       bool            *isInputError )
...
void InsertionSort( SortArray   data,
                    int         firstElement,
                    int         lastElement )

The endline approach is neat and aesthetically appealing. The main problem is that it takes a lot of work to maintain, and styles that are hard to maintain aren't maintained. Suppose that the function name changes from ReadEmployeeData() to ReadNewEmploy-eeData(). That would throw the alignment of the first line off from that of the other four lines. You'd have to reformat the other four lines of the parameter list to align with the new position of maxEmployees caused by the longer function name. And you'd probably run out of space on the right side since the elements are so far to the right already.

The examples shown in Example 31-64, formatted using standard indentation, are just as appealing aesthetically but take less work to maintain.

public bool ReadEmployeeData(
   int maxEmployees,
   EmployeeList *employees,
   EmployeeFile *inputFile,
   int *employeeCount,
   bool *isInputError
)
...

public void InsertionSort(
   SortArray data,
   int firstElement,
   int lastElement
)

This style holds up better under modification. If the routine name changes, the change has no effect on any of the parameters. If parameters are added or deleted, only one line has to be modified—plus or minus a comma. The visual cues are similar to those in the indentation scheme for a loop or an if statement. Your eye doesn't have to scan different parts of the page for every individual routine to find meaningful information; it knows where the information is every time.

This style translates to Visual Basic in a straightforward way, though it requires the use of line-continuation characters, as shown in Example 31-65:

Public Sub ReadEmployeeData ( _       <-- 1
   ByVal maxEmployees As Integer, _
   ByRef employees As EmployeeList, _
   ByRef inputFile As EmployeeFile, _
   ByRef employeeCount As Integer, _
   ByRef isInputError As Boolean _
)