The C Users' Group Library 1994 August/wc-cdrom-cusersgrouplibrary-1994-08.iso/vol_100/137_01/feb84col.ddj

Text File | 1979-12-31 | 20KB | 535 lines

.pl 60
.po 0
..
.. "The C/Unix Programmer's Notebook"
..
.. DDJ Column #2        as of 19-Sep-83
.. (C) 1983 Anthony Skjellum.   All rights reserved.
.. For publication in DDJ
..
..
.. file (DDJCOL2.WS)        created:  24-Nov-83
..                updated:  24-Nov-83
..                updated:  25-Nov-83
..
..                completed: 25-Nov-83
..
.he "C/Unix Programmer's Notebook" by Anthony Skjellum. (C) 1983. For 2/84 DDJ.

                               Introduction

..
    In the first installment of this column,  I proposed a standard for

the  layout  of C code (see DDJ #84,  October,  1983.)  Significant  reader

response  was received concerning this subject.   The vast majority of  the

letters received were in favor of the concept of a C layout  standard.   In

this column, I will present reader comments concerning the layout standard,

and discuss some modifications and additions to the proposed standard based

on reader suggestions.

..
    Some  comments  were  also  received concerning  my  discussion  of

runtime library and linkage format incompatibilities.   Discussion of these

points will be left for a future column.

                  Modifying the Proposed Layout Standard

                        I. Questions of White Space

..
    Several readers took exception to a particular point concerning the

proposed layout standard.   This was point 4f. which states "No white space

character  is  placed between a keyword (e.g.  if)  and  its  parenthesized

argument."  David D. Clark of State College, Pennsylvania, writes:

..
    "In  general,  I like your coding standard  suggestions.   My  only
strong  objection  is your idea to leave out spaces between reserved  words
[and their arguments].  It makes them look like function invocations."

    Tim Smith of Evanston, Illinois, notes:

..
    "...I  think  that a single space between a function name  and  the
initial opening parenthesis, or after "if's" and "elses", looks better..."

    Guy Scharf of Mountainview, California writes:

..
    "4f.   I  have a strong preference to always put a space between  a
reserved word (e.g.  if,  while) and its parenthesized argument.  This adds
legibility for me."

    Finally, Charlie Brady of New South Wales, Australia, writes:

..
    "The  only real beef I have with you is the formatting of  keywords
and  their parenthetical expressions.   I can see no reason to depart  from
Kernighan  and  Ritchie  on  this  point,  and  a  number  of  reasons  for
maintaining  their  convention.   Firstly,  a  flow  control  construct  is
semantically distinct from a function call,  and a formatting difference is
a  reasonable  way  of  distinguishing  them.    Secondly,  the  formatting
difference  simplifies  the  use  of  a  text  editor  for  such  tasks  as
constructing structure charts.   Third, your recommendation departs from at
least  three  extant recommended standards,  namely Kernighan and  Ritchie,
Thomas  Plum  (C Standards and Guidelines,  Plum-Hall 1981)  and  Tim  Lang
(Formatting C,  AUUGN Vol 4,  No 1, Jan 1982. Enclosed)."  (I want to thank
Mr.  Brady for including a copy of the Lang article with his letter.  The C
standard proposed there is very compatible with the one I have proposed.)

..
    After considering the above remarks,  I have come to the conclusion

that  the space really does serve a useful purpose.   Therefore,  I suggest

that  point 4f.  should be changed to read:  "A single white  character  is

(optionally)  placed  between  a keyword (e.g.  if) and  its  parenthesized

argument."  (Making the white space character optional is another point for

debate.)  I think it should be optional,  but recommended.   I don't  think

that  adding a space for function call invocations would be beneficial,  as

suggested by Mr. Smith.

..
    Another   question  concerning  white  space  insertion  comes   in

connection with argument lists.  The original standard does not indicate if

spaces  should  be  included.   It is my opinion that  a  comma  should  be

directly adjacent to the argument that it follows,  and that a single white

space should follow each comma to add legibility.  I am also convinced that

parentheses  should be adjacent to the argument(s) they enclose.   Thus (in

agreement with Tim Lang's article mentioned above) I would write:

        x = atan(sin(y));

and not

        x = atan(  sin( y ) );

..
    Yet another point not previously mentioned is that binary operators

should be delimited by white space.   Thus,  the following statement  lacks

sufficient white space:

        v = sin(ln(1.0+x));

while this expression is properly formed:

        v = sin(ln(1.0 + x));

..
    Finally,  section  4  needs  to  be  updated  to  include  a  style

specification for pointer references.   I think that that operators '.' and

'->'  should not be delimited by spaces from the objects which they act on.

This point and the three above are formalized in Figure I.  as additions to

section 4.

.pa
              ------------------FIGURE I.--------------------

    (Under section 4)

         b.  Binary operators (e.g.  +,  -, / but not '->' and '.') and
                 assignment operators (eg =, *=, &=) are delimited by white
                 space.

         g.  Parentheses  should be adjacent to the  argument(s)  which
                 they enclose.

         h.  A comma is bound to the argument which preceeds and should
                 be followed by a single space.


         i.  Operators   such  as  '->'  and  '.'  (used   in   pointer
                 references)  directly  bind  to their  arguments  with  no
                 intervening spaces.

          ---------------------END FIGURE I.--------------------


..
    The  Lang article points out a circumstance under which  point  9g.

need  not  be  followed.   This occurs when  very  complicated  conditional

expressions of the form "keyword (expr)" are split over several lines.  For

example,  instead  of using a crowded expression as illustrated in  Example

1a.,  a  more  readable  form is selected (see Example 1b.)  Note  that  in

Example 1b.  that the parentheses are placed on lines by themselves,  since

they  bracket  a  multiline  expression,   much  like  braces  enclose  the

statements of a block.

           --------------------Example Ia.---------------------

        if((a  == 1) && (b == 2) && (c == 3) && ((d == 4) || (d == 5)))
        {
            /* operations performed if conditional true */
            ...
        }

          --------------------End Example Ia.--------------------

           --------------------Example Ib.---------------------

        if    /* we make multi-line expression look like a block */
        (
            (a == 1) &&
            (b == 2) &&
            (c == 3) &&
            ((d == 4) || (d == 5))
        )
        {
            /* operations performed if conditional true */
            ...
        }

          --------------------End Example Ib.--------------------

..
    Another  point  of  minor  objection  was  the  tabulation   method

specified  by  the  standard (point 1a.).   Steve Newberry  of  Los  Altos,

California, states:

..
    "Upon one point I do feel compelled to argue with you,  and that is
the  tab convention:   The DEPTH of the tab stop on a given page is of  far
less  significance to the readability of that page than is the  CONSISTENCY
of  the depth.   I REALLY don't want to use different size tabs on the same
page."

    Tim Smith writes:

    "I personally follow most all of his suggestions on how to actually
format the code on the line and page,  with only two exceptions.   I ALWAYS
use 4-space tab stops..."

..
    I  agree  that  having a single tab size is the preferable  way  to

write  C  code.   Standard tabs give more openness to the  code,  and  make

various  parts  of a program easier to pick out.   My rationale  for  large

horizontal  tabbing  is  the same as for  vertical  tabbing.   I  want  the

program's  significant  portions to stand out.  However,  I propose  adding

point 1b.  to the standard:  "4-space tabs may be used in lieu of  standard

tabs  in  cases  where a sub-program includes highly nested  segments."   I

would  also  include point 1c.:  "Only one of the two  tabbing  conventions

should be employed in any given program module."

..
    Some  currently available screen editors provide a  feature  called

horizontal scrolling.   With horizontal scrolling,  the user views a window

of  his file in both the vertical and horizontal directions.   Thus,  files

with  lines  longer than the display device may be  handled  intelligently.

Under such circumstances,  there is no real disadvantage to using  standard

tabs to any desired nesting depth,  which is permitted by point 1a.  of the

proposed standard.
                          II. Other corrections.

..
    Charlie  Brady pointed out an unnecessary point in section 3 (point

3e) which stated:  "When a null block is used (e.g. "{}"), it may appear on

the same line as other statements (e.g. do {} while(expr);).  He writes:

..
    "Another  minor point of disagreement concerns the use of the  null
block ({}).  This is never necessary, and I believe that the null statement
(;) is clearer.  It should be emphasised that the null statement deserves a
line of its own.  Your example:

        do {} while(expr);

is more simply written

        while (expr)
            ;

..
    In accordance with Mr. Brady's remark, I propose replacing point 3e

with the following:   "The null block ({}) can always be avoided.   Instead

of a null block,  use the null statement."  I also would add point  3f#ii.:

"The null statement is always on a line by itself."


                       III. Documentation Standards

..
    In  addition to a code layout standard,  James Halstead of  Joliet,

Illinois, has proposed a basic documentation standard.  He writes:

..
    "...I strongly suggest that the original standards one through nine
be  renumbered two through ten so that the first and foremost standard  may
be  inserted."   The documentation standard suggested by  Mr.  Halstead  is
presented  in Figure II.  and I think it should be included in my  proposed
standard.   However, I have decided to number the documentation standard as
section  0.  in  order to preserve the numbering of the  current  sections.
(Slight  additions  which  I  made  include  an  asterisk  to  indicate  my
addition.)

.pa
             -------------------FIGURE II.-------------------

    0.   Identification  Description (I.D.) information must appear  at
         the beginning of each C language source file.

         a.  The recommended format is:

                  i.    Begin comment (/*).
                  ii.   Space.
                 iii.  Title (identification name normally = filename).
          *  iv.   Sub-title (ie what program system does this file
                                    belong to).
                 v.    Space.
                 vi.   Classification (see below).
                 vii.  Year.
                 viii. Owner.
                 ix.   Status (see below).
              *  x.    Current Version number and brief history.
                 xi.   Date.
                 xii.  Functional/Structural Description in brief.
          *  xiii. Portability synopsis.
          *     xiv.  Space.
                 xv.   End Comment (*/).
              *  xvi.  Space.

         b.  The program classification (vi.) is one of the following:

                 i.    public-domain.
                 ii.   copyright.
              *  iii.  copyright: released for non-commercial purposes.
                 iv.   unclassified.
                 v.    secret.
                 vi.   no classification.

         c.  The program status (ix.) is one of the following:

                 i.    outline.
                 ii.   draft.
         iii.  test (alpha, beta etc.)
                 iv.   release.

           -------------------END FIGURE II.--------------------

.pa
..
    In  addition to Section 0.,  I think a basic documentation standard

is in order for functions as well.   Such a standard is presented in Figure

III.   I  have  placed this under section 10,  since I  think  of  function

documentation  is a separate task from module documentation as described in

section 0.

             -------------------FIGURE III.-------------------

    10.  Each   function   should   contain   the   following   minimum
             documentation:

             a.   A general explanation of the function performed.
             b.   Its  name,  and a description of its arguments  including
                  their types, and legal values.
             c.   A description of the functional return value, if any.
             d.   A list of non-standard functions used by the function.
             e.   A list of external variables used and/or modified by
                  the function.
         f.   A description of the error handling characteristics of the
            function.
             g.   A valid calling sequence example, if practical.

          -------------------END FIGURE III.--------------------


                            IV. Other proposals

..
    Several other readers made suggestions for the standard.   I  think

that Tim Smith proposes several which merit discussion.  They are presented

here with the point numbers they receive as part of the standard:

    (5c).  Don't  nest  comments,  even if  your  preprocessor/compiler
               allows it.

    (6f).  If there are many declarations, whether on one line or many,
               alphabetize them.

    (9g).  Restrict  variable  and  function  names  to  7  well-chosen
               characters, even if your compiler allows more.

    Steve Newberry writes the following about standards:

..
    "I   applaud  your  interest  in  establishing  a  standard  format
convention for C programs.  However I feel that your effort would have more
impact  if tied to support of Tom Plum's book C Programming  Standards  and
Guidelines, Version U (Unix and offspring), Edition 3: Jan. '82.  Presented
in  this  manner,  your  proposed formatting standard would be  seen  as  a
consistent  extension  of a more general set of standards already  in  wide
circulation."

                           Other points of View

    Although  most  readers  were favorable to the idea of a  C  format

standard, Douglas M. Potter of Seattle, Washington, writes:

    "I afraid I don't see much advantage of your proposed standard over
theirs [Kernighan and Ritchie].   In both cases,  the size of the ident  is
too  large,  I  always run out of room on the right side with a  tab  sized
ident.  I also find that nobody uses enough white space."

    John F. Draffen of Texas City, Texas, wrote me a detailed letter on

why he didn't like the idea.  He writes:

    "I  am writing to express my objections...In the first place  I  do
not  think a standard of this type is either necessary or  desirable.   The
layout  has  nothing  to do with portability which to my mind is  the  only
excuse for a standard.  It seems to me that it is hard enough to get people
to agree on necessary standards."

    "In  the second place I do not agree with many of your  suggestions
on  style.   One of the nice things about C that it shares with Fortran  is
it's  relative  conciseness.   I  do  not  like  to  see  code  strung  out
unnecessarily.  C does not interject unnecessary constructions, and I think
that  introducing  unnecessary  white  space,   excessive  indentation  and
meaningless comments is a kind of gingerbread that we can do without."  Mr.
Draffen's style philosophy is listed in Figure IV.

            --------------------FIGURE IV.--------------------

    1.  Punctuation  should  be  used  sparingly.    The  insertion  of
            unnecessary white space should be avoided.

    2.  Block  structure  should  be  used  indicated  by  indentation.
            Excessive indentation should be avoided.

        3.  Comments and program code should be separated.  Comments on the
            same  line as code should be displaced far enough to the  right
            that they do not obscure the code.

        4.  Comments  should be meaningful.   Comments that do no more than
            repeat  what  has  already  been said by  the  code  should  be
            avoided.

         ----------------------END FIGURE IV.---------------------

    I don't really agree with Mr. Draffen on several counts.  First and

foremost  is  that  portability is not the sole subject  of  importance  in

programming.  The ability to maintain, understand, correct and enhance code

is of great importance.   To understand someone else's code,  (or your  own

code  at a later date) requires some degree of formatting.   Comments which

seem  less than essential to the programmer must sometimes be included  for

the sake of others.   This is immensely important.   It is often  difficult

for a programmer to know how to comment his code, since he usually can  not

know  the  level of sophistication of later readers.   Thus,  it  is  often

better to include a few extra comments, than to comment code sparsely.

    I  suggested in my previous column that users should maintain their

own code in the form that they prefer.  However, code distributed to others

could  (and should) meet some minimum standard of neatness (ie  formatting)

and  presentation.   Some of this can be provided by a beautifier but  most

must be done by the programmer himself.

    As  one  final  note  on C  layout,  I'm  including  an  insightful

paragraph which Tim Smith included his letter.   It suggests why so much  C

code is so poorly formatted and commented:

    "I  don't think,  however,  that you will ever get Unix wizards  to
follow these recommendations.  I should have noted that I use Skjellum-like
conventions   when   I'm  writing  micro-based  applications.    When   I'm
maintaining Unix sources I stick with the standard Unix conventions,  which
are pretty much K & R [Kernighan and Ritchie] standard.   Unix whiz's think
that aligning curly braces is irrelevant,  since "vi", the editor which 90%
of them use, will always let you find the top or bottom match for any brace
automatically.   Also, and probably more important, Unix system guys always
debug  by staring at their CRT's,  never from printouts (that's  for  COBOL
programmers),  and the goal is to reduce the number of lines of a function,
so  that  as much of it as possible will fit on a screen.   Seeing a  WHOLE
LINE taken up by just an opening brace must drive them whacko,  and some of
them will even close blocks on the end of a line of code (yecch!)"

                                Conclusion

..
    In  this column,  I have presented additions and corrections to the

proposed layout standard,  based on reader response.  I have also presented

the opposing point of view.  Most of the letters received were positive, so

it was difficult to include more dissenting remarks.  I want to thank those

who sent in their comments about the standard.