home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_100 / 137_01 / sep83tab.i < prev    next >
Text File  |  1979-12-31  |  7KB  |  155 lines
  1.                                  Table I.
  2.  
  3.                     Proposed Standard for C Code Layout
  4.  
  5.  
  6.     I.    Standard tabs are used for program indentation.
  7.  
  8.          a. Four space tabs may be used, if desired, after column 56. 
  9.                     This is permitted in order to prevent line wrap on             
  10.                     80-column displays.
  11.  
  12.     II.   A brace is generally on a line by itself.
  13.  
  14.           a. The lowest level braces appear on the left margin.
  15.  
  16.          b. Comments  may appear on lines containing a brace,  but only 
  17.                     after the brace.
  18.  
  19.          c. Braces are indented to the same depth as the statement 
  20.                     which invoked the block they frame.
  21.  
  22.          d. In variable initializations, the opening brace may be 
  23.                     placed on the same line as the equal sign, but the closing 
  24.                     brace must have the same indentation as the opening one.
  25.  
  26.          e. In general, no statements may appear on the same line as a 
  27.                     brace.
  28.  
  29.  
  30.  
  31.     III.  A block begins with a left brace and ends with a right brace. Its 
  32.               contents are indented an extra level to indicate the  nesting 
  33.               depth.
  34.  
  35.          a. Whenever a block is longer than 24 lines (a standard  CRT 
  36.                     page), a comment should follow the closing brace to
  37.             indicate the block which the brace closes. 
  38.             i.  This applies to whole functions as well as regular 
  39.                             blocks.
  40.                         ii. This  rule  should  also be  applied  with  shorter 
  41.                             blocks  when  block nesting makes the code  complex 
  42.                             and these comments improve the readability.
  43.  
  44.          b. The opening and closing braces of a block are always 
  45.                     indented indentically.
  46.  
  47.          c. The  case/default labels of a switch statement  are  always 
  48.                     indented   a  level  like  statements  in  a  block.    The 
  49.                     statements which follow these labels are always indented an 
  50.                     extra level to improve readability.
  51.  
  52.          d. Regular labels (destinations for goto's) are always placed 
  53.                     at the left margin, regardless of nesting depth.
  54.  
  55.          e. When a null block is used (eg '{}'), it may appear on the 
  56.                     same line as statements (eg do {} while(expr);).
  57.  
  58.          f. If  a single statement is used instead of a  block,  it  is 
  59.                     indented  a single level,  just as if it were surrounded by 
  60.                     braces.
  61.             i.  Null statements (ie just a ';') are indented in the 
  62.                             same way as regular statements.
  63.  
  64.     IV.  White space is added in expressions and assignments to improve  
  65.              readability.
  66.  
  67.          a. Relational operators are delimited by single spaces.
  68.  
  69.          b. Equal signs are delimited by single spaces.
  70.  
  71.          c. Unary operators are not separated by space from their 
  72.                     operands.
  73.  
  74.          d. Parentheses are added to improve readability in complex 
  75.                     expressions, even if they are not required to produce 
  76.                     correct evaluation.
  77.             i.  A return statement always has a set of parentheses 
  78.                             surrounding its expression.
  79.  
  80.          e. No white space character is placed between function names 
  81.                     and their parenthesized argument list.
  82.  
  83.          f. No white space character is placed between a keyword (eg. 
  84.                     if) and its parenthesized argument.
  85.  
  86.     V.   Comments are added liberally to make the program read easily.
  87.  
  88.          a. If a comment requires more than one line, the start/end 
  89.                     comment tokens are placed on lines containing no comment 
  90.                     text. In this case, the start/end tokens are indented 
  91.                     identically.
  92.  
  93.          b. If a comment fits on a single line, the start/end tokens 
  94.                     must also be placed on that line.
  95.  
  96.     VI.   Variables are always declared, even if your version of C has a 
  97.               default type.  Always explain the purpose of your variables.
  98.  
  99.          a. Declare the variables in logical groups, and include a 
  100.                     comment on the same line as the declaration to describe the 
  101.                     function(s) of the variable(s).
  102.  
  103.              b. Avoid numerous declarations on a single line.
  104.  
  105.          c. Explain complex pointer declarations.
  106.  
  107.          d. Variable names are always lower case only.
  108.  
  109.          e. External variable declarations may be indented a single 
  110.                     level for greater readability.
  111.  
  112.     VII.  Constants created with #define are always upper case.  Macros 
  113.               created with #define may be upper or lower case.
  114.  
  115.          a. As with variables, constants should have explanatory com-
  116.                     ments to explain their purpose.
  117.  
  118.          b. Macros should be explained via comments to avoid mis-
  119.                     understandings about their uses.  This is especially 
  120.                     important since macros tend to be cryptic.
  121.  
  122.          c. Restrict #define statements to the beginning of code files 
  123.                     (ie before the first function).  This avoids the potential 
  124.                     for redefinition and other confusion.
  125.  
  126.     VIII. Other items.
  127.  
  128.          a. The else..if(expr) construct is placed on a single line as 
  129.                     if it were a single keyword.
  130.  
  131.          b. Function names are always lower case.
  132.  
  133.     IX.   Portability considerations.
  134.  
  135.          a. When using a non-standard C feature, always prepare a 
  136.                     portable alternative which may be selected via conditional 
  137.                     compilation.
  138.  
  139.                  b. Indicate any subtle uses of sign extension and type 
  140.                     conversions made by your program or your specific compiler.
  141.  
  142.                  c. Indicate any deviations in the way your compiler handles 
  143.                     pointer arithmetic.
  144.  
  145.                  d. Include the ampersand operator ('&') when you pass pointers 
  146.                     to structures, even if your compiler doesn't require it.  
  147.                     Someone else's compiler may support passing structures.
  148.  
  149.          e. Indicate any deviations of your runtime library from 
  150.                     the standard.  
  151.  
  152.                  f. Indicate any deviation in the (argc,argv) command line 
  153.                     conventions made by your compiler.
  154.  
  155.