home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / standards.info-1 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  49KB  |  912 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: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
  20. Version
  21. *******
  22.    Last updated 21 September 1994.
  23. * Menu:
  24. * Preface::            About the GNU Coding Standards
  25. * Reading Non-Free Code::    Referring to Proprietary Programs
  26. * Contributions::        Accepting Contributions
  27. * Change Logs::            Recording Changes
  28. * Compatibility::        Compatibility with Other Implementations
  29. * Makefile Conventions::    Makefile Conventions
  30. * Configuration::        How Configuration Should Work
  31. * Source Language::        Using Languages Other Than C
  32. * Formatting::            Formatting Your Source Code
  33. * Comments::            Commenting Your Work
  34. * Syntactic Conventions::    Clean Use of C Constructs
  35. * Names::            Naming Variables and Functions
  36. * Using Extensions::        Using Non-standard Features
  37. * System Functions::            Portability and "standard" library functions
  38. * Semantics::            Program Behavior for All Programs
  39. * Errors::            Formatting Error Messages
  40. * Libraries::            Library Behavior
  41. * Portability::            Portability As It Applies to GNU
  42. * User Interfaces::        Standards for Command Line Interfaces
  43. * Documentation::        Documenting Programs
  44. * Releases::            Making Releases
  45. File: standards.info,  Node: Preface,  Next: Reading Non-Free Code,  Prev: Top,  Up: Top
  46. About the GNU Coding Standards
  47. ******************************
  48.    The GNU Coding Standards were written by Richard Stallman and other
  49. GNU Project volunteers.  Their purpose is to make the GNU system clean,
  50. consistent, and easy to install.  This document can also be read as a
  51. guide to write portable, robust and reliable programs.  It focuses on
  52. programs written in C, but many of the rules and principles are useful
  53. even if you write in another programming language.  The rules often
  54. state reasons for writing in a certain way.
  55.    Corrections or suggestions regarding this document should be sent to
  56. `gnu@prep.ai.mit.edu'.  If you make a suggestion, please include a
  57. suggested new wording for it; our time is limited.  We prefer a context
  58. diff to the `standards.texi' or `make-stds.texi' files, but if you
  59. don't have those files, please mail your suggestion anyway.
  60.    This release of the GNU Coding Standards was last updated 21
  61. September 1994.
  62. File: standards.info,  Node: Reading Non-Free Code,  Next: Contributions,  Prev: Preface,  Up: Top
  63. Referring to Proprietary Programs
  64. *********************************
  65.    Don't in any circumstances refer to Unix source code for or during
  66. your work on GNU!  (Or to any other proprietary programs.)
  67.    If you have a vague recollection of the internals of a Unix program,
  68. this does not absolutely mean you can't write an imitation of it, but
  69. do try to organize the imitation internally along different lines,
  70. because this is likely to make the details of the Unix version
  71. irrelevant and dissimilar to your results.
  72.    For example, Unix utilities were generally optimized to minimize
  73. memory use; if you go for speed instead, your program will be very
  74. different.  You could keep the entire input file in core and scan it
  75. there instead of using stdio.  Use a smarter algorithm discovered more
  76. recently than the Unix program.  Eliminate use of temporary files.  Do
  77. it in one pass instead of two (we did this in the assembler).
  78.    Or, on the contrary, emphasize simplicity instead of speed.  For some
  79. applications, the speed of today's computers makes simpler algorithms
  80. adequate.
  81.    Or go for generality.  For example, Unix programs often have static
  82. tables or fixed-size strings, which make for arbitrary limits; use
  83. dynamic allocation instead.  Make sure your program handles NULs and
  84. other funny characters in the input files.  Add a programming language
  85. for extensibility and write part of the program in that language.
  86.    Or turn some parts of the program into independently usable
  87. libraries.  Or use a simple garbage collector instead of tracking
  88. precisely when to free memory, or use a new GNU facility such as
  89. obstacks.
  90. File: standards.info,  Node: Contributions,  Next: Change Logs,  Prev: Reading Non-Free Code,  Up: Top
  91. Accepting Contributions
  92. ***********************
  93.    If someone else sends you a piece of code to add to the program you
  94. are working on, we need legal papers to use it--the same sort of legal
  95. papers we will need to get from you.  *Each* significant contributor to
  96. a program must sign some sort of legal papers in order for us to have
  97. clear title to the program.  The main author alone is not enough.
  98.    So, before adding in any contributions from other people, tell us so
  99. we can arrange to get the papers.  Then wait until we tell you that we
  100. have received the signed papers, before you actually use the
  101. contribution.
  102.    This applies both before you release the program and afterward.  If
  103. you receive diffs to fix a bug, and they make significant change, we
  104. need legal papers for it.
  105.    You don't need papers for changes of a few lines here or there, since
  106. they are not significant for copyright purposes.  Also, you don't need
  107. papers if all you get from the suggestion is some ideas, not actual code
  108. which you use.  For example, if you write a different solution to the
  109. problem, you don't need to get papers.
  110.    I know this is frustrating; it's frustrating for us as well.  But if
  111. you don't wait, you are going out on a limb--for example, what if the
  112. contributor's employer won't sign a disclaimer?  You might have to take
  113. that code out again!
  114.    The very worst thing is if you forget to tell us about the other
  115. contributor.  We could be very embarrassed in court some day as a
  116. result.
  117. File: standards.info,  Node: Change Logs,  Next: Compatibility,  Prev: Contributions,  Up: Top
  118. Change Logs
  119. ***********
  120.    Keep a change log for each directory, describing the changes made to
  121. source files in that directory.  The purpose of this is so that people
  122. investigating bugs in the future will know about the changes that might
  123. have introduced the bug.  Often a new bug can be found by looking at
  124. what was recently changed.  More importantly, change logs can help
  125. eliminate conceptual inconsistencies between different parts of a
  126. program; they can give you a history of how the conflicting concepts
  127. arose.
  128.    Use the Emacs command `M-x add-change' to start a new entry in the
  129. change log.  An entry should have an asterisk, the name of the changed
  130. file, and then in parentheses the name of the changed functions,
  131. variables or whatever, followed by a colon.  Then describe the changes
  132. you made to that function or variable.
  133.    Separate unrelated entries with blank lines.  When two entries
  134. represent parts of the same change, so that they work together, then
  135. don't put blank lines between them.  Then you can omit the file name
  136. and the asterisk when successive entries are in the same file.
  137.    Here are some examples:
  138.      * register.el (insert-register): Return nil.
  139.      (jump-to-register): Likewise.
  140.      
  141.      * sort.el (sort-subr): Return nil.
  142.      
  143.      * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
  144.      Restart the tex shell if process is gone or stopped.
  145.      (tex-shell-running): New function.
  146.      
  147.      * expr.c (store_one_arg): Round size up for move_block_to_reg.
  148.      (expand_call): Round up when emitting USE insns.
  149.      * stmt.c (assign_parms): Round size up for move_block_from_reg.
  150.    It's important to name the changed function or va