style.gml

开放源码的编译器open watcom 1.6.0版的源代码

.ix style
.ix 'programming style'
.pp
Programming style is as individual as a person's
preference in clothing.
Unfortunately, just as some programmers wouldn't
win a fashion contest, some code has poor style. This code is
usually easy to spot, because it is difficult to understand.
.pp
Good programming style can make the difference between programs
that are easy to debug and modify, and those that you just want to
avoid.
.pp
There are a number of aspects to programming style. There is no
perfect style that is altogether superior to all others. Each programmer
must find a style that makes him or her comfortable.
The intention is to write code that is easy to read and understand,
not to try to stump the next person who has to fix a problem in
the code.
.pp
Good programming style will also lead to less time spent writing a
program, and certainly less time spent debugging or modifying it.
.pp
The following sections discuss various aspects of programming style.
They reflect the author's own biases, but they are biases based
on years of hacking his way through
code, mostly good and some bad, and much of it his own!
.*
.section Consistency
.*
.pp
Perhaps
the most important aspect of style is
.ix 'style' 'consistency'
.us consistency
..ct ..li .
Try, as much as possible, to use the same rules throughout the entire
program.
Having a mixed bag of styles within one program will confuse even the
best of programmers trying to decipher the code.
.pp
If more than one programmer is involved in the project, it may be
appropriate, before the first line of code is written, to discuss
general rules of style. Some rules are more important than others.
Make sure everyone understands the rules, and are encouraged to
follow them.
.*
.section Case Rules for Object and Function Names
.*
.pp
When examining a piece of code, the scope of an object is sometimes
difficult to determine. One needs to examine the declarations of
objects within the function, then those declared outside of any
functions, then those declared included from other source files.
If no strict rules of naming objects are followed, each place will
need to be laboriously searched each time.
.pp
.ix 'name' 'mixed case'
.ix 'style' 'case rules'
Using mixed case object names, with strict rules, can make the job
much easier.
It does not matter what rules are established, as long as the rules
are consistently applied throughout the program.
.pp
Consider the following sample set of rules, used throughout this book:
.autonote
.note
objects declared within a function
with
.ix 'automatic storage duration'
.ix 'storage duration' automatic
automatic storage duration
are entirely in lower case,
.millust begin
int        x, counter, limit;
float      save_global;
struct s * sptr;
.millust end
.note
objects with
.ix 'static storage duration'
.ix 'storage duration' static
static storage duration (global objects)
start with an upper
case letter, and words or word fragments also start with
upper case,
.millust begin
static int      TotalCount;
extern float    GlobalAverage;
static struct s SepStruct;
.millust end
.note
function names start with an upper case letter, and words or word
fragments also start with upper case, (distinguishable from global objects
by the left parenthesis),
.millust begin
extern int     TrimLength( char * ptr, int len );
static field * CreateField( char * name );
.millust end
.note
all
.ix 'manifest constant'
.ix constant manifest
.ix constant '#define'
.ix constant 'enumeration'
constants are entirely in upper case.
.millust begin
#define FIELD_LIMIT 500
#define BUFSIZE     32

enum { INVALID, HELP, ADD, DELETE, REPLACE };
.millust end
.note
all
.ix 'type definition'
.kw typedef
tags are in upper case.
.millust begin
typedef struct {
    float real;
    float imaginary;
} COMPLEX;
.millust end
.endnote
.pc
Thus, the storage duration and scope of each identifier can be
determined without regard to context. Consider this program fragment:
.millust begin
    chr = ReadChar();
    if( chr != EOF ) {
        GlbChr = chr;
    }
.millust end
.pc
Using the above rules,
.autonote
.note
.mono ReadChar
is a function,
.note
.mono chr
is an object
with automatic storage duration
defined within the current function,
.note
.mono EOF
is a constant,
.note
.mono GlbChr
is an object with static storage duration.
.endnote
.pp
Note: the
.ix 'library function'
library functions do not use mixed case names.
Also, the function
.ix 'function' main
.mono main
does not begin with an upper case
.mono M.
Using the above coding style, library functions would stand out from
other functions because of the letter-case difference.
.*
.section Choose Appropriate Names
.*
.pp
.ix style 'object names'
The naming of objects can be critical to the ease with which
bugs can be found, or changes can be made. Using object names such
as
.mono linecount, columns
and
.mono rownumber
will make the program more readable. Of course, short forms
will creep into the code (few programmers
like to type more than is really
necessary), but they should be used judiciously.
.pp
Consistency of naming also helps
to make the code more readable. If a structure is used throughout the
program, and many different routines need a pointer to that structure,
then the name of each object that points to it could be made the same.
Using the example of a symbol table, the object name
.mono symptr
might be used everywhere to mean "pointer to a symbol structure".
A programmer seeing that object will automatically know what it is
declared to be.
.pp
Appropriate function names are also very important. Names such as
.mono DoIt
..ct ,
while saving the original programmer from trying to think of a good
name, make it more difficult for the next programmer to figure out
what is going on.
.*
.section Indent to Emphasize Structure
.*
.ix style indenting
.pp
The following is a valid function:
.millust begin
static void BubbleSort( int list[], int n )
/**********************************/ { int index1
= 0; int index2; int temp; if( n < 2 )return; do {
index2 = index1 + 1; do { if( list[ index1 ] >
list[ index2 ] ) { temp = list[ index1 ]; list[
index1 ] = list[ index2 ]; list[ index2 ] = temp;
} } while( ++index2 < n ); } while( ++index1 < n-1
); }
.millust end
.pc
(The compiler will know that it's valid, but the programmer would
find it difficult to validate.)
Here is the same function, but using indenting to clearly illustrate
the function structure:
.millust begin
static void BubbleSort( int list[], int n )
/*****************************************/
  {
    int index1 = 0;
    int index2;
    int temp;

    if( n < 2 )return;
    do {
        index2 = index1 + 1;
        do {
            if( list[ index1 ] > list[ index2 ] ) {
                temp = list[ index1 ];
                list[ index1 ] = list[ index2 ];
                list[ index2 ] = temp;
            }
        } while( ++index2 < n );
    } while( ++index1 < n-1 );
  }
.millust end
.pp
Generally, it is good practice to indent each level of code by a
consistent amount, for example 4 spaces. Thus, the subject of
an
.kw if
statement is always indented 4 spaces inside the
.kw if
..ct ..li .
In this manner, all loop and selection statements will stand out,
making it easier to determine when the statements end.
.pp
The following are some recommended patterns to use when indenting
statements.
These patterns have been used throughout the book.
.millust begin
int Fn( void )
/************/
{
    /* indent 4 */
}
.millust break
..sk 1 c
if( condition ) {
    /* indent 4 */
} else {
    /* indent 4 */
}
.millust break
..sk 1 c
if( condition ) {
    /* indent 4 */
} else if( condition ) {
    /* indent 4 from first if */
    if( condition ) {
        /* indent 4 from nearest if */
    }
} else {
    /* indent 4 from first if */
}
.millust break
..sk 1 c
switch( condition ) {
  case VALUE:
    /* indent 4 from switch */
  case VALUE:
  default:
}
.millust break
..sk 1 c
do {
    /* indent 4 */
while( condition );
.millust break
..sk 1 c
while( condition ) {
    /* indent 4 */
}
.millust break
..sk 1 c
for( a; b; c ) {
    /* indent 4 */
}
.millust end
.keep begin
.pc
Two other popular indenting styles are,
.millust begin
if( condition )
  {
    :ITAL.statement:eITAL.
  }
.millust end
.keep break
.pc
and,
.millust begin
if( condition )
{
    :ITAL.statements:eITAL.
}
.millust end
.keep end
.pc
It is not important which style is used. However, a consistent style
is an asset.
.*
.section Visually Align Object Declarations
.*
.ix style 'aligning declarations'
.pp
A lengthy series of object declarations can be difficult to read if
care is not taken to improve the readability. Consider the
declarations,