standards.texi

早期freebsd实现

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename standards.info
@settitle GNU Coding Standards
@c %**end of header

@ifinfo
@format
START-INFO-DIR-ENTRY
* standards: (standards).	GNU Project Coding Standards
END-INFO-DIR-ENTRY
@end format
@end ifinfo


@setchapternewpage off

@ifinfo
Copyright (C) 1992 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end ifinfo

@titlepage
@sp 10
@titlefont{GNU Coding Standards}
@author{Richard Stallman}
@author{last updated 16 Jul 1992}
@c Note date also appears below.
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1992 Free Software Foundation

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by Free Software Foundation.
@end titlepage

@ifinfo
@node Top, Reading Non-Free Code, (dir), (dir)
@top Version

Last updated 16 Jul 1992.
@c Note date also appears above.
@end ifinfo

@menu
* Reading Non-Free Code::	Referring to Proprietary Programs
* Contributions::		Accepting Contributions
* Change Logs::			Recording Changes
* Compatibility::		Compatibility with Other Implementations
* Makefiles::			Makefile Conventions
* Configuration::		How Configuration Should Work
* Source Language::		Using Languages Other Than C
* Formatting::			Formatting Your Source Code
* Comments::			Commenting Your Work
* Syntactic Conventions::	Clean Use of C Constructs
* Names::			Naming Variables and Functions
* Using Extensions::		Using Non-standard Features
* Semantics::			Program Behaviour for All Programs
* Errors::			Formatting Error Messages
* Libraries::			Library Behaviour
* Portability::			Portability As It Applies to GNU
* User Interfaces::		Standards for Command Line Interfaces
* Documentation::		Documenting Programs
* Releases::			Making Releases
@end menu

@node Reading Non-Free Code
@chapter Referring to Proprietary Programs

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
@chapter Accepting Contributions

If someone else sends you a piece of code to add to the program you are
working on, we need legal papers to use it---the same sort of legal
papers we will need to get from you.  @emph{Each} significant
contributor 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, 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 change, we
need legal papers for it.

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 you write a different solution to the
problem, you don't need to get papers.

I know this is frustrating; 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!

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.

@node Change Logs
@chapter Change Logs

Keep a change log for each directory, describing the changes made to
source files in that directory.  The purpose of this is so that people
investigating bugs in the future will know about the changes that
might have introduced the bug.  Often a new bug can be found by
looking at what was recently changed.  More importantly, change logs
can help eliminate conceptual inconsistencies between different parts
of a program; they can give you a history of how the conflicting
concepts arose.

Use the Emacs command @kbd{M-x add-change} to start a new entry in the
change log.  An entry should have an asterisk, the name of the changed
file, and then in parentheses the name of the changed functions,
variables or whatever, followed by a colon.  Then describe the changes
you made to that function or variable.

Separate unrelated entries with blank lines.  When two entries
represent parts of the same change, so that they work together, then
don't put blank lines between them.  Then you can omit the file name
and the asterisk when successive entries are in the same file.

Here are some examples:

@example
* register.el (insert-register): Return nil.
(jump-to-register): Likewise.

* sort.el (sort-subr): Return nil.

* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
Restart the tex shell if process is gone or stopped.
(tex-shell-running): New function.

* expr.c (store_one_arg): Round size up for move_block_to_reg.
(expand_call): Round up when emitting USE insns.
* stmt.c (assign_parms): Round size up for move_block_from_reg.
@end example

There's no need to describe here the full purpose of the changes or how
they work together.  It is better to put this explanation in comments in
the code.  That's why just ``New function'' is enough; there is a
comment with the function in the source to explain what it does.

However, sometimes it is useful to write one line to describe the
overall purpose of a large batch of changes.

You can think of the change log as a conceptual ``undo list'' which
explains how earlier versions were different from the current version.
People can see the current version; they don't need the change log
to tell them what is in it.  What they want from a change log is a
clear explanation of how the earlier version differed.

When you change the calling sequence of a function in a simple
fashion, and you change all the callers of the function, there is no
need to make individual entries for all the callers.  Just write in
the entry for the function being called, ``All callers changed.''

When you change just comments or doc strings, it is enough to write an
entry for the file, without mentioning the functions.  Write just,
``Doc fix.''  There's no need to keep a change log for documentation
files.  This is because documentation is not susceptible to bugs that
are hard to fix.  Documentation does not consist of parts that must
interact in a precisely engineered fashion; to correct an error, you
need not know the history of the erroneous passage.


@node Compatibility
@chapter Compatibility with Other Implementations

With certain exceptions, utility programs and libraries for GNU should
be upward compatible with those in Berkeley Unix, and upward compatible
with @sc{ANSI} C if @sc{ANSI} 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.

@sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions.  Feel
free to make the extensions anyway, and include a @samp{--ansi} 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.  Try to redesign its
interface.

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,
vi is replaced with Emacs.)  But it is nice to offer a compatible
feature as well.  (There is a free vi clone, so we offer it.)

Additional useful features not in Berkeley Unix are welcome.
Additional programs with no counterpart in Unix may be useful,
but our first priority is usually to duplicate what Unix already
has.


@node Makefiles
@chapter Makefile Conventions

This chapter describes conventions for writing Makefiles.

@menu
* Makefile Basics::
* Standard Targets::
* Command Variables::
* Directory Variables::
@end menu

@node Makefile Basics
@section General Conventions for Makefiles

Every Makefile should contain this line:

@example
SHELL = /bin/sh
@end example

@noindent
to avoid trouble on systems where the @code{SHELL} variable might be
inherited from the environment.

Don't assume that @file{.} is in the path for command execution.  When
you need to run programs that are a part of your package during the
make, please make sure that it uses @file{./} if the program is built as
part of the make or @file{$(srcdir)/} if the file is an unchanging part
of the source code.  Without one of these prefixes, the current search
path is used.  

The distinction between @file{./} and @file{$(srcdir)/} is important
when using the @samp{--srcdir} option to @file{configure}.  A rule of
the form:

@example
foo.1 : foo.man sedscript
	sed -e sedscript foo.man > foo.1
@end example

@noindent
will fail when the current directory is not the source directory,
because @file{foo.man} and @file{sedscript} are not in the current
directory.

Relying on @samp{VPATH} to find the source file will work in the case
where there is a single dependency file, since the @file{make} automatic
variable @samp{$<} will represent the source file wherever it is.  A
makefile target like

@example
foo.o : bar.c
	$(CC) $(CFLAGS) -I. -I$(srcdir) -c bar.c -o foo.o
@end example

@noindent
should instead be written as

@example
foo.o : bar.c
	$(CC) $(CFLAGS) $< -o $@
@end example

@noindent
in order to allow @samp{VPATH} to work correctly.  When the target has
multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
way to make the rule work well.  For example, the target above for
@file{foo.1} is best written as:

@example
foo.1 : foo.man sedscript
	sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
@end example

@node Standard Targets
@section Standard Targets for Users

All GNU programs should have the following targets in their Makefiles:

@table @samp
@item all
Compile the entire program.

@item install
Compile the program and copy the executables, libraries, and so on to
the file names where they should reside for actual use.  If there is a
simple test to verify that a program is properly installed then run that
test.

Use @samp{-} before any command for installing a man page, so that
@code{make} will ignore any errors.  This is in case there are systems
that don't have the Unix man page documentation system installed.

@item clean
Delete all files from the current directory that are normally created by
building the program.  Don't delete the files that record the
configuration.  Also preserve files that could be made by building, but
normally aren't because the distribution comes with them.