home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #1
/
monster.zip
/
monster
/
PROG_C
/
SNIP9404.ZIP
/
C_PORT.TXT
< prev
next >
Wrap
Text File
|
1994-04-03
|
13KB
|
341 lines
=====[ Ed Hopper's BBS #1 ]=====[ 8-04-91 ]=====[ 9:55.22 ]=====
Date: 08-02-91 (09:40) C-Lang Number: 26406 (Echo)
To: ALL
From: JOSEPH CARNAGE Read: 08-03-91 (10:56)
City: DUNEDIN FL Last On: 02-28-91 (22:53)
Subj: Portable, clean code #1
How to write portable clean source code
---------------------------------------
A common concern with programmers new to Axiom is writing portable
code. There a number of tricks and guide lines which may help with
this. In no particular order:
-- Use full ANSI prototypes with all arguments declared. For
function pointers, declare their expected arguments. For
prototypes for functions which accept function pointers, do not
declare the expected arguments for the function pointer
argument.
It is good practice to put dummy variable names in prototypes as
this adds readability.
-- Explicitly type all variables and functions. Never rely on them
defaulting to int.
-- Pay a little care to the ternary operator ? :, and parenthesize
heavily. A very few compilers have problems with the default
order of evaluation for the ternary operator.
-- Never ever name a variable identically to a function. This is
most especially true of statics or globals. This sort of error
can cause weird hidden linker problems which cause bizarre
results at runtime and are difficult to trace.
-- Never ever name a screen, form, data field etc identically to a
variable or function as this can cause weird and non-reported
linker errors in the final executable which can be very
difficult to locate.
-- Do not nest comments. If you want to block off a section of
code temporarily, use #ifdef/#endif. eg.
...code...
#ifdef JUNK /* Unwanted code */
...more code...
#endif /* JUNK */
...yet more code...
-- Run PC-Lint on all code, and handle ALL errors and warnings.
-- Read the "Frequently Asked Questions" document and understand
fully.
-- Read K&R thoroughly and everywhere it mentions "implementation
dependant", or "new" features not "supported by all compilers",
avoid those areas. Examples are bit fields, passing structures
to functions, returning structures from functions, and the
volatile type. These are not supported by all compilers.
-- In areas where the ANSI standard advances on the old K&R, but
still allows the K&R form, follow K&R. An example is using
function pointers. If you are unsure what areas this covers,
don't worry, just stick with K&R. eg.
Given:
int (*prj_afunc) (); /* Pointer to function which returns int */
ANSI allows the pointed to function be called as so:
prj_afunc (xxx, yyy);
K&R specifies that it should be called:
*prj-afunc (xxx, yyy);
Use the K&R form, which ANSI still allows, and all compilers
support.
-- Do not use the new // comments. Stay with the /* comment */
form.
-- Do not indent #ifdefs, #defines, #pragmas, or other preprocessor
directives. Some compilers allow code as such:
#ifdef DEBUG
#define TEST 1
#endif
or
#ifdef FINAL
# ifdef DEBUG
# define TEST 1
# endif
#endif
But by no means all. Use white space if needed to delineate
#ifdef/endif blocks and comment liberally:
#ifdef FINAL
#ifdef DEBUG
#define TEST 1
#endif /* DEBUG*/
#endif /* FINAL */
-- Do not use the ANSI string literal concatenation features. eg.
printf ("This is ANSI but"
"unportable code.\n");
for long string literals. Under ANSI the the compiler should
concatenate the two string literals into one, but not all ANSI
compilers support this feature yet. If you need a very long
string literal use a form as so:
printf ("%s%s",
"this is",
"portable code.\n");
or just use a very long string literal.
-- Stay away from ints except for trash and temp values. Ints vary
in size depending upon the memory model under DOS, and legally
may be any size between shorts and longs inclusive.
Try to use shorts or longs if possible, as these are of fairly
constant size on most platforms. On most platforms, but by no
means all, shorts are usually words and longs word pairs.
-- Beware of assigning a pointer of one type to a pointer of a
higher type. Most platforms seem to insist that the addresses
stored in pointers are alligned per the pointer's base type.
What this means is that the value stored in a pointer to a long,
in itself will be alligned as a long is. If longs are alligned
on even word boundaries, then so will the value of long pointer.
This can result in memory allignment errors which can be
extremely difficult to track down. Casting will not help.
DOS has few memory allignment requirements, but for Unix and VMS
you can expect types to be alligned to their sizes (see the
compiler manuals for specifics). What this means to pointers is
that with code such as:
short *pj2_value; /* Assume that shorts are alligned to words */
long *pj4_number; /* and longs to even word boundaries */
pj4_number = pj2_value;
that the value assigned to pj4_number may be as far as two bytes
different from that in pj2_value. ie
Let's say that the address stored is pj2_value is:
*pj2_value == 0000:0006 /* Alligned to word */
and you make the assignment:
pj4_number = pj2_value;
After this, the value of pj4_number will be either 0000:0004,
or 0000:0008 to shift it to even word allignment. The
direction of the shift seems to be compiler/implementation
dependant.
This bug is often erratic at runtime depending upon the
allignment of automatics. This sort of bug is especically
difficult to track when coming up from a void pointer.
-- Be wary of relying on memory allignment in structures and
unions. Different compiler implmentations allign differently,
and #pragmas or command line arguments to the compiler can
change allignment at compile time. See the compiler manuals for
specific details.
This will usually require you to either read in each member
individually, or to perform explicit padding when reading
structure data from disk. eg. lic1.c & v_lic_pad() in the Axiom
library.
-- Where possible use sizeof(identifier) rather than sizeof(type)
or a #defined constant. This can help in tracing down bugs and
makes for greater readability. eg.
#define M_DATA 100
short aj2_numbers[M_DATA];
/* This example requires the reader to remember that
aj2_numbers has M_DATA elements, is overly complex, and
presumes that aj2_numbers will always be shorts. This code
will likely break if anything is later changed. */
memcpy (aj2_numbers, pj2_input, M_DATA * sizeof (short));
/* This is ideal -- sizeof(aj2_numbers) will return the total
space allocated to the array, no matter what the type may be,
or what is changed later. It makes no assumptions of the
reader. */
memcpy (aj2_numbers, pj2_input, sizeof (aj2_numbers));
-- Beware of comparing structures or unions with functions such as
memcmp() as the padding/allignment spaces will have random and
likely different values. If you need to compare structures
you'll have to do it member by member.
-- Never assign structures to each other directly. Some compilers
allow structure assignments, some don't.
struct t_data s_struc1;
struct t_data s_struc2;
s_struc2 = s_struc1; /* Unportable code */
Note however that you can copy structures via pointers as need
be:
struct t_data *ps_struc1;
struct t_data *ps_struc2;
ps_struc1 = xxx;
ps_struc2 = yyy;
*ps_struc2 = *ps_struc1; /* Copy structure 1 to 2 */
Rather than assigning each member over individually. The
functions memcpy() and memmove() are other portable ways.
-- Beware of passing chars or shorts to functions. These get
promoted to ints, and with some compilers problems from there on
out abound horrendously. This is especially true of chars where
some compilers occassionally extract the wrong byte from the
promoted int in the recieving function.
-- Be careful passing floats to functions as some compilers promote
floats to doubles when passing them as an argument. This can
cause spurious warnings and and strange side effects.
-- Explicitly cast assignments and expressions as needed, and
carefully watch that you really don't need to make those
identifiers of that type originally. While the promotion order
is constant across implementations, the size of the types
aren't. This can cause difficult side effects.
If your code needs a lot of casts to get past Lint, then you
probably need to rethink some of your approaches.
-- Take care to cast all #defined constants if in doubt. For large
values (longs), always cast as longs, or place an 'L' at the end
of the constant. Some compilers handle this area erraticly if
left up to them.
-- Never ever rely on order of evaluation of function parameters.
This can occur when listing a funtion call as a parameter to
another funtion, or as an unintentional side effect from passing
assignments or function calls as parameters.
char *pc_modify (char *);
printf ("This string [%s] becomes [%s]\n",
pc_string, pc_modify (pc_string)); /* Bad code */
-- Do not use NULL for anything but pointers. Do not use NULL for
string terminations: use the ASCII constant NUL, '\0', or a
#defined type which equates to that.
-- Never EVER pass a #defined macro an incremented or decremented
value (++,or --) or an assignment as a parameter. This is
because many #defined macros may reference their arguments
multiple times. This is especially true of the macros #defined
in ctype.h.
eg.
#define iscsymf(c) (isalpha(c) || ((c) == '_'))
If called as so:
iscsym(var++);
it will be expanded by the preprocessor to:
(isalpha(var++) || ((var++) == '_'))
with var being incremented twice.
-- Avoid passing any functions incremented or decremented values
("++" or "--"), or assignments. Some standard and commercial
library calls are actually #defined macros. This type of
"error" can lead to order of evaluation problems as different
compilers process function arguments in different orders.
-- Explicitly initialise pointers. Do not rely on calloc(),
memset() or other such functions to initialise pointers.
Initialise them explicitly.
"K&R" as mentioned above refers to "The C Programming Language"
written by Brian W Kernighan & Dennis M Ritchie.
"PC-Lint" is a commercial version of Lint for the PC, as sold by
Gimpel Software. PC-Lint is generally acknowledged as the tightest
and most discerning Lint on any platform.
There are several books which cover the areas of portable code which
may also help:
"C Programming Guidelines"
by Thomas Plum
pub. by Plum Hall
ISBN 0-911537-03-1
"Portability and the C Language"
by Rex Jaeschke
pub. by Hayden Books
ISBN 0-672-48428-5
"Portable C Software"
by Mark R. Horton
pub. by Prentice Hall
ISBN 0-13-868050-7
"Portable C"
by Henry Rabinowitz & Chaim Schaap
pub. by Prentice Hall
ISBN 0-13-685967-4
"Portable C and Unix System Programming"
by J.E. Lapin
pub. Prentice-Hall
ISBN 0-13-686494-5
[END]