31.7. Laying Out Routines

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.

Cross-Reference

For details on documenting routines, see "Commenting Routines" in Section 32.5. For details on the process of writing a routine, see Section 9.3, "Constructing Routines by Using the PPP." For a discussion of the differences between good and bad routines, see Chapter 7, "High-Quality 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. Listing 31-62 shows two examples of routine headers with no conscious layout:

Listing 31-62. C++ 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. Listing 31-63 shows the same routine headers reformatted:

Listing 31-63. C++ example of routine headers with mediocre endline layout

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.

Cross-Reference

For more details on using routine parameters, see Section 7.5, "How to Use Routine Parameters."

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

Listing 31-64. C++ example of routine headers with readable, maintainable standard indentation

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 Listing 31-65:

Listing 31-65. Visual Basic example of routine headers with readable, maintainable standard indentation

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

(1)Here's the "_" character used as a line-continuation character.