standards.texi

LINUX下的源码工具,可自己分析,或者直接装在系统上作为应用

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
@set lastupdate November 23, 2002
@c %**end of header

@dircategory GNU organization
@direntry
* Standards: (standards).        GNU coding standards.
@end direntry

@c @setchapternewpage odd
@setchapternewpage off

@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp

@c This is used by a cross ref in make-stds.texi
@set CODESTD  1
@iftex
@set CHAPTER chapter
@end iftex
@ifinfo
@set CHAPTER node
@end ifinfo

@copying
The GNU coding standards, last updated @value{lastupdate}.

Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
2001, 2002 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no
Front-Cover Texts, and with no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end copying

@titlepage
@title GNU Coding Standards
@author Richard Stallman, et al.
@author last updated @value{lastupdate}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Preface, (dir), (dir)
@top Version

@insertcopying
@end ifnottex

@menu
* Preface::                     About the GNU Coding Standards
* Legal Issues::                Keeping Free Software Free
* Design Advice::               General Program Design
* Program Behavior::            Program Behavior for All Programs
* Writing C::                   Making The Best Use of C
* Documentation::               Documenting Programs
* Managing Releases::           The Release Process
* References::                  References to Non-Free Software or Documentation
* Copying This Manual::         How to Make Copies of This Manual
* Index::                       

@end menu

@node Preface
@chapter About the GNU Coding Standards

The GNU Coding Standards were written by Richard Stallman and other GNU
Project volunteers.  Their purpose is to make the GNU system clean,
consistent, and easy to install.  This document can also be read as a
guide to writing portable, robust and reliable programs.  It focuses on
programs written in C, but many of the rules and principles are useful
even if you write in another programming language.  The rules often
state reasons for writing in a certain way.

This release of the GNU Coding Standards was last updated
@value{lastupdate}.

@cindex where to obtain @code{standards.texi}
@cindex downloading this manual
If you did not obtain this file directly from the GNU project and
recently, please check for a newer version.  You can get the GNU
Coding Standards from the GNU World Wide Web server host in several
different formats: @uref{http://www.gnu.org/prep/standards.text},
@uref{http://www.gnu.org/prep/standards.info}, and
@uref{http://www.gnu.org/prep/standards.dvi}, as well as the
Texinfo ``source'' which is divided in two files:
@uref{http://www.gnu.org/prep/standards.texi} and
@uref{http://www.gnu.org/prep/make-stds.texi}.  The GNU Coding
Standards are also available in HTML format starting at
@uref{http://www.gnu.org/prep/standards_toc.html}.

Corrections or suggestions for this document should be sent to
@email{bug-standards@@gnu.org}.  If you make a suggestion, please include a
suggested new wording for it; our time is limited.  We prefer a context
diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
you don't have those files, please mail your suggestion anyway.

These standards cover the minimum of what is important when writing a
GNU package.  Likely, the needs for additional standards will come up.
Sometimes, you might suggest that such standards be added to this
document.  If you think your standards would be generally useful, please
do suggest them.

You should also set standards for your package on many questions not
addressed or not firmly specified here.  The most important point is to
be self-consistent---try to stick to the conventions you pick, and try
to document them as much as possible.  That way, your program will be
more maintainable by others.

The GNU Hello program serves as an example of how to follow the GNU
coding standards for a trivial program which prints @samp{Hello,
world!}.  @uref{http://www.gnu.org/software/hello/hello.html}.

@node Legal Issues
@chapter Keeping Free Software Free
@cindex legal aspects

This @value{CHAPTER} discusses how you can make sure that GNU software
avoids legal difficulties, and other related issues.

@menu
* Reading Non-Free Code::       Referring to Proprietary Programs
* Contributions::               Accepting Contributions
* Trademarks::                  How We Deal with Trademark Issues
@end menu

@node Reading Non-Free Code
@section Referring to Proprietary Programs
@cindex proprietary programs
@cindex avoiding proprietary code

Don't in any circumstances refer to Unix source code for or during
your work on GNU!  (Or to any other proprietary programs.)

If you have a vague recollection of the internals of a Unix program,
this does not absolutely mean you can't write an imitation of it, but
do try to organize the imitation internally along different lines,
because this is likely to make the details of the Unix version
irrelevant and dissimilar to your results.

For example, Unix utilities were generally optimized to minimize
memory use; if you go for speed instead, your program will be very
different.  You could keep the entire input file in core and scan it
there instead of using stdio.  Use a smarter algorithm discovered more
recently than the Unix program.  Eliminate use of temporary files.  Do
it in one pass instead of two (we did this in the assembler).

Or, on the contrary, emphasize simplicity instead of speed.  For some
applications, the speed of today's computers makes simpler algorithms
adequate.

Or go for generality.  For example, Unix programs often have static
tables or fixed-size strings, which make for arbitrary limits; use
dynamic allocation instead.  Make sure your program handles NULs and
other funny characters in the input files.  Add a programming language
for extensibility and write part of the program in that language.

Or turn some parts of the program into independently usable libraries.
Or use a simple garbage collector instead of tracking precisely when
to free memory, or use a new GNU facility such as obstacks.

@node Contributions
@section Accepting Contributions
@cindex legal papers
@cindex accepting contributions

If the program you are working on is copyrighted by the Free Software
Foundation, then when someone else sends you a piece of code to add to
the program, we need legal papers to use it---just as we asked you to
sign papers initially.  @emph{Each} person who makes a nontrivial
contribution to a program must sign some sort of legal papers in order
for us to have clear title to the program; the main author alone is not
enough.

So, before adding in any contributions from other people, please tell
us, so we can arrange to get the papers.  Then wait until we tell you
that we have received the signed papers, before you actually use the
contribution.

This applies both before you release the program and afterward.  If
you receive diffs to fix a bug, and they make significant changes, we
need legal papers for that change.

This also applies to comments and documentation files.  For copyright
law, comments and code are just text.  Copyright applies to all kinds of
text, so we need legal papers for all kinds.

We know it is frustrating to ask for legal papers; it's frustrating for
us as well.  But if you don't wait, you are going out on a limb---for
example, what if the contributor's employer won't sign a disclaimer?
You might have to take that code out again!

You don't need papers for changes of a few lines here or there, since
they are not significant for copyright purposes.  Also, you don't need
papers if all you get from the suggestion is some ideas, not actual code
which you use.  For example, if someone send you one implementation, but
you write a different implementation of the same idea, you don't need to
get papers.

The very worst thing is if you forget to tell us about the other
contributor.  We could be very embarrassed in court some day as a
result.

We have more detailed advice for maintainers of programs; if you have
reached the stage of actually maintaining a program for GNU (whether
released or not), please ask us for a copy.

@node Trademarks
@section Trademarks
@cindex trademarks

Please do not include any trademark acknowledgements in GNU software
packages or documentation.

Trademark acknowledgements are the statements that such-and-such is a
trademark of so-and-so.  The GNU Project has no objection to the basic
idea of trademarks, but these acknowledgements feel like kowtowing, so
we don't use them.  There is no legal requirement for them.

What is legally required, as regards other people's trademarks, is to
avoid using them in ways which a reader might read as naming or labeling
our own programs or activities.  For example, since ``Objective C'' is
(or at least was) a trademark, we made sure to say that we provide a
``compiler for the Objective C language'' rather than an ``Objective C
compiler''.  The latter is meant to be short for the former, but it does
not explicitly state the relationship, so it could be misinterpreted as
using ``Objective C'' as a label for the compiler rather than for the
language.

@node Design Advice
@chapter General Program Design
@cindex program design

This @value{CHAPTER} discusses some of the issues you should take into
account when designing your program.

@c                         Standard or ANSI C
@c
@c In 1989 the American National Standards Institute (ANSI) standardized
@c C   as  standard  X3.159-1989.    In  December   of  that   year  the
@c International Standards Organization ISO  adopted the ANSI C standard
@c making  minor changes.   In 1990  ANSI then  re-adopted  ISO standard
@c C. This version of C is known as either ANSI C or Standard C.

@c A major revision of the C Standard appeared in 1999.

@menu
* Source Language::             Which languges to use.
* Compatibility::               Compatibility with other implementations
* Using Extensions::            Using non-standard features
* Standard C::                  Using Standard C features
* Conditional Compilation::     Compiling Code Only If A Conditional is True
@end menu

@node Source Language
@section Which Languages to Use
@cindex programming languges

When you want to use a language that gets compiled and runs at high
speed, the best language to use is C.  Using another language is like
using a non-standard feature: it will cause trouble for users.  Even if
GCC supports the other language, users may find it inconvenient to have
to install the compiler for that other language in order to build your
program.  For example, if you write your program in C++, people will
have to install the GNU C++ compiler in order to compile your program.

C has one other advantage over C++ and other compiled languages: more
people know C, so more people will find it easy to read and modify the
program if it is written in C.

So in general it is much better to use C, rather than the
comparable alternatives.

But there are two exceptions to that conclusion:

@itemize @bullet
@item
It is no problem to use another language to write a tool specifically
intended for use with that language.  That is because the only people
who want to build the tool will be those who have installed the other
language anyway.

@item
If an application is of interest only to a narrow part of the community,
then the question of which language it is written in has less effect on
other people, so you may as well please yourself.
@end itemize

Many programs are designed to be extensible: they include an interpreter
for a language that is higher level than C.  Often much of the program
is written in that language, too.  The Emacs editor pioneered this
technique.

@cindex GUILE
The standard extensibility interpreter for GNU software is GUILE, which
implements the language Scheme (an especially clean and simple dialect
of Lisp).  @uref{http://www.gnu.org/software/guile/}.  We don't reject
programs written in other ``scripting languages'' such as Perl and
Python, but using GUILE is very important for the overall consistency of
the GNU system.

@node Compatibility
@section Compatibility with Other Implementations
@cindex compatibility with C and @sc{posix} standards
@cindex @sc{posix} compatibility

With occasional exceptions, utility programs and libraries for GNU
should be upward compatible with those in Berkeley Unix, and upward
compatible with Standard C if Standard C specifies their
behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
their behavior.

When these standards conflict, it is useful to offer compatibility
modes for each of them.

@cindex options for compatibility
Standard C and @sc{posix} prohibit many kinds of extensions.  Feel
free to make the extensions anyway, and include a @samp{--ansi},
@samp{--posix}, or @samp{--compatible} option to turn them off.
However, if the extension has a significant chance of breaking any real
programs or scripts, then it is not really upward compatible.  So you
should try to redesign its interface to make it upward compatible.

@cindex @code{POSIXLY_CORRECT}, environment variable
Many GNU programs suppress extensions that conflict with @sc{posix} if the
environment variable @code{POSIXLY_CORRECT} is defined (even if it is
defined with a null value).  Please make your program recognize this
variable if appropriate.

When a feature is used only by users (not by programs or command
files), and it is done poorly in Unix, feel free to replace it
completely with something totally different and better.  (For example,
@code{vi} is replaced with Emacs.)  But it is nice to offer a compatible
feature as well.  (There is a free @code{vi} clone, so we offer it.)

Additional useful features are welcome regardless of whether
there is any precedent for them.

@node Using Extensions
@section Using Non-standard Features
@cindex non-standard extensions

Many GNU facilities that already exist support a number of convenient
extensions over the comparable Unix facilities.  Whether to use these
extensions in implementing your program is a difficult question.

On the one hand, using the extensions can make a cleaner program.
On the other hand, people will not be able to build the program
unless the other GNU tools are available.  This might cause the
program to work on fewer kinds of machines.

With some extensions, it might be easy to provide both alternatives.
For example, you can define functions with a ``keyword'' @code{INLINE}
and define that as a macro to expand into either @code{inline} or
nothing, depending on the compiler.

In general, perhaps it is best not to use the extensions if you can
straightforwardly do without them, but to use the extensions if they
are a big improvement.

An exception to this rule are the large, established programs (such as
Emacs) which run on a great variety of systems.  Using GNU extensions in
such programs would make many users unhappy, so we don't do that.

Another exception is for programs that are used as part of compilation:
anything that must be compiled with other compilers in order to
bootstrap the GNU compilation facilities.  If these require the GNU
compiler, then no one can compile them without having them installed
already.  That would be extremely troublesome in certain cases.

@node Standard C
@section Standard C and Pre-Standard C
@cindex @sc{ansi} C standard

1989 Standard C is widespread enough now that it is ok to use its
features in new programs.  There is one exception: do not ever use the
``trigraph'' feature of Standard C.

1999 Standard C is not widespread yet, so please do not require its
features in programs.  It is ok to use its features if they are present.

However, it is easy to support pre-standard compilers in most programs,
so if you know how to do that, feel free.  If a program you are
maintaining has such support, you should try to keep it working.

@cindex function prototypes
To support pre-standard C, instead of writing function definitions in
standard prototype form,

@example
int
foo (int x, int y)
@dots{}
@end example

@noindent
write the definition in pre-standard style like this,

@example
int
foo (x, y)
     int x, y;
@dots{}
@end example

@noindent
and use a separate declaration to specify the argument prototype:

@example
int foo (int, int);
@end example

You need such a declaration anyway, in a header file, to get the benefit
of prototypes in all the files where the function is called.  And once
you have the declaration, you normally lose nothing by writing the
function definition in the pre-standard style.

This technique does not work for integer types narrower than @code{int}.
If you think of an argument as being of a type narrower than @code{int},
declare it as @code{int} instead.

There are a few special cases where this technique is hard to use.  For
example, if a function argument needs to hold the system type
@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
@code{int} on some machines; but you cannot use @code{int} instead,
because @code{dev_t} is wider than @code{int} on some machines.  There
is no type you can safely use on all machines in a non-standard
definition.  The only way to support non-standard C and pass such an
argument is to check the width of @code{dev_t} using Autoconf and choose
the argument type accordingly.  This may not be worth the trouble.

In order to support pre-standard compilers that do not recognize
prototypes, you may want to use a preprocessor macro like this:

@example
/* Declare the prototype for a general external function.  */
#if defined (__STDC__) || defined (WINDOWSNT)
#define P_(proto) proto
#else
#define P_(proto) ()
#endif
@end example

@node Conditional Compilation
@section Conditional Compilation

When supporting configuration options already known when building your
program we prefer using @code{if (... )} over conditional compilation,
as in the former case the compiler is able to perform more extensive
checking of all possible code paths.