home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / standards.info-2 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  44KB  |  1,198 lines
  1. This is Info file ../standards.info, produced by Makeinfo-1.55 from the
  2. input file ../standards.texi.
  3. START-INFO-DIR-ENTRY
  4. * Standards: (standards).        GNU coding standards.
  5. END-INFO-DIR-ENTRY
  6.    GNU Coding Standards Copyright (C) 1992, 1993, 1994 Free Software
  7. Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Free Software Foundation.
  19. File: standards.info,  Node: Syntactic Conventions,  Next: Names,  Prev: Comments,  Up: Top
  20. Clean Use of C Constructs
  21. *************************
  22.    Please explicitly declare all arguments to functions.  Don't omit
  23. them just because they are `int's.
  24.    Declarations of external functions and functions to appear later in
  25. the source file should all go in one place near the beginning of the
  26. file (somewhere before the first function definition in the file), or
  27. else should go in a header file.  Don't put `extern' declarations inside
  28. functions.
  29.    It used to be common practice to use the same local variables (with
  30. names like `tem') over and over for different values within one
  31. function.  Instead of doing this, it is better declare a separate local
  32. variable for each distinct purpose, and give it a name which is
  33. meaningful.  This not only makes programs easier to understand, it also
  34. facilitates optimization by good compilers.  You can also move the
  35. declaration of each local variable into the smallest scope that includes
  36. all its uses.  This makes the program even cleaner.
  37.    Don't use local variables or parameters that shadow global
  38. identifiers.
  39.    Don't declare multiple variables in one declaration that spans lines.
  40. Start a new declaration on each line, instead.  For example, instead of
  41. this:
  42.      int    foo,
  43.             bar;
  44. write either this:
  45.      int foo, bar;
  46. or this:
  47.      int foo;
  48.      int bar;
  49. (If they are global variables, each should have a comment preceding it
  50. anyway.)
  51.    When you have an `if'-`else' statement nested in another `if'
  52. statement, always put braces around the `if'-`else'.  Thus, never write
  53. like this:
  54.      if (foo)
  55.        if (bar)
  56.          win ();
  57.        else
  58.          lose ();
  59. always like this:
  60.      if (foo)
  61.        {
  62.          if (bar)
  63.            win ();
  64.          else
  65.            lose ();
  66.        }
  67.    If you have an `if' statement nested inside of an `else' statement,
  68. either write `else if' on one line, like this,
  69.      if (foo)
  70.        ...
  71.      else if (bar)
  72.        ...
  73. with its `then'-part indented like the preceding `then'-part, or write
  74. the nested `if' within braces like this:
  75.      if (foo)
  76.        ...
  77.      else
  78.        {
  79.          if (bar)
  80.            ...
  81.        }
  82.    Don't declare both a structure tag and variables or typedefs in the
  83. same declaration.  Instead, declare the structure tag separately and
  84. then use it to declare the variables or typedefs.
  85.    Try to avoid assignments inside `if'-conditions.  For example, don't
  86. write this:
  87.      if ((foo = (char *) malloc (sizeof *foo)) == 0)
  88.        fatal ("virtual memory exhausted");
  89. instead, write this:
  90.      foo = (char *) malloc (sizeof *foo);
  91.      if (foo == 0)
  92.        fatal ("virtual memory exhausted");
  93.    Don't make the program ugly to placate `lint'.  Please don't insert
  94. any casts to `void'.  Zero without a cast is perfectly fine as a null
  95. pointer constant.
  96. File: standards.info,  Node: Names,  Next: Using Extensions,  Prev: Syntactic Conventions,  Up: Top
  97. Naming Variables and Functions
  98. ******************************
  99.    Please use underscores to separate words in a name, so that the Emacs
  100. word commands can be useful within them.  Stick to lower case; reserve
  101. upper case for macros and `enum' constants, and for name-prefixes that
  102. follow a uniform convention.
  103.    For example, you should use names like `ignore_space_change_flag';
  104. don't use names like `iCantReadThis'.
  105.    Variables that indicate whether command-line options have been
  106. specified should be named after the meaning of the option, not after
  107. the option-letter.  A comment should state both the exact meaning of
  108. the option and its letter.  For example,
  109.      /* Ignore changes in horizontal whitespace (-b).  */
  110.      int ignore_space_change_flag;
  111.    When you want to define names with constant integer values, use
  112. `enum' rather than `#define'.  GDB knows about enumeration constants.
  113.    Use file names of 14 characters or less, to avoid creating gratuitous
  114. problems on System V.  You can use the program `doschk' to test for
  115. this.  `doschk' also tests for potential name conflicts if the files
  116. were loaded onto an MS-DOS file system--something you may or may not
  117. care about.
  118. File: standards.info,  Node: Using Extensions,  Next: System Functions,  Prev: Names,  Up: Top
  119. Using Non-standard Features
  120. ***************************
  121.    Many GNU facilities that already exist support a number of convenient
  122. extensions over the comparable Unix facilities.  Whether to use these
  123. extensions in implementing your program is a difficult question.
  124.    On the one hand, using the extensions can make a cleaner program.
  125. On the other hand, people will not be able to build the program unless
  126. the other GNU tools are available.  This might cause the program to
  127. work on fewer kinds of machines.
  128.    With some extensions, it might be easy to provide both alternatives.
  129. For example, you can define functions with a "keyword" `INLINE' and
  130. define that as a macro to expand into either `inline' or nothing,
  131. depending on the compiler.
  132.    In general, perhaps it is best not to use the extensions if you can
  133. straightforwardly do without them, but to use the extensions if they
  134. are a big improvement.
  135.    An exception to this rule are the large, established programs (such
  136. as Emacs) which run on a great variety of systems.  Such programs would
  137. be broken by use of GNU extensions.
  138.    Another exception is for programs that are used as part of
  139. compilation: anything that must be compiled with other compilers in
  140. order to bootstrap the GNU compilation facilities.  If these require
  141. the GNU compiler, then no one can compile them without having them
  142. installed already.  That would be no good.
  143.    Since most computer systems do not yet implement ANSI C, using the
  144. ANSI C features is effectively using a GNU extension, so the same
  145. considerations apply.  (Except for ANSI features that we discourage,
  146. such as trigraphs--don't ever use them.)
  147. File: standards.info,  Node: System Functions,  Next: Semantics,  Prev: Using Extensions,  Up: Top
  148. Calling System Functions
  149. ************************
  150.    C implementations differ substantially.  ANSI C reduces but does not
  151. eliminate the incompatibilities; meanwhile, many users wish to compile
  152. GNU software with pre-ANSI compilers.  This chapter gives
  153. recommendations for how to use the more or less standard C library
  154. functions to avoid unnecessary loss of portability.
  155.    * Don't use the value of `sprintf'.  It returns the number of
  156.      characters written on some systems, but not on all systems.
  157.    * Don't declare system functions explicitly.
  158.      Almost any declaration for a system function is wrong on some
  159.      system.  To minimize conflicts, leave it to the system header
  160.      files to declare system functions.  If the headers don't declare a
  161.      function, let it remain undeclared.
  162.      While it may seem unclean to use a function without declaring it,
  163.      in practice this works fine for most system library functions on
  164.      the systems where this really happens.  The problem is only
  165.      theoretical.  By contrast, actual declarations have frequently
  166.      caused actual conflicts.
  167.    * If you must declare a system function, don't specify the argument
  168.      types.  Use an old-style declaration, not an ANSI prototype.  The
  169.      more you specify abo