Comments

Properly-commented driver code is much easier to maintain. The following types of comments are recommended:

• A block comment for the entire driver should identify the devices supported by the driver (including version numbers and hardware strapping values), the derivation of the driver (is it a modified version of another driver?), date of creation, and the operating system releases for which it was written and has been tested.

• Describe each global data structure or type that is declared, including its possible range of values. Describe the protocol, if any, used to access it (such as flag-setting or locking calls). If it is useful, describe the functions that access it, including those that are in other files.

• A block comment at the beginning of each entry point routine and driver subroutine should describe what it does, how it does it (algorithms and strategies), the arguments that are used, assumptions about the environment when it is called (synchronization constraints, outstanding I/O jobs, and so forth), possible return values from the entry point or subroutine, and what global variables are used.

• Each line that declares an argument to the routine should have a comment.

• Each line that declares a local variable of the routine should have a comment, unless it is a trivial variable such as a loop counter.

• Each control structure that is defined should have a comment explaining the structure's purpose, how it is populated, and how it is updated.

• Each significant loop or ``if'' test should have a comment at the beginning that explains what it is testing.

• The // delimiter for comments in C language drivers is acceptable but is less portable than the traditional /* xxx */ delimiter.