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