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.
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005