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