@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate March 28, 2011
+@set lastupdate December 31, 2011
@c %**end of header
@dircategory GNU organization
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
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. It is also available
-online for your perusal: @uref{http://www.gnu.org/prep/maintain/}.
+We have more detailed advice for maintainers of GNU packages. If you
+have reached the stage of maintaining a GNU program (whether released
+or not), please take a look: @pxref{Legal Matters,,, maintain,
+Information for GNU Maintainers}.
+
@node Trademarks
@section Trademarks
were later adopted as part of the standard. If you want these
constructs to give an error message as ``required'' by the standard,
you must specify @samp{--pedantic}, which was implemented only so that
-we can say ``GCC is a 100% implementation of the standard,'' not
+we can say ``GCC is a 100% implementation of the standard'', not
because there is any reason to actually use it.
POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by
POSIX is never a problem in practice, and it is very useful.
In particular, don't reject a new feature, or remove an old one,
-merely because a standard says it is ``forbidden'' or ``deprecated.''
+merely because a standard says it is ``forbidden'' or ``deprecated''.
+
@node Semantics
@section Writing Robust Programs
are silently truncated''. This is not acceptable in a GNU utility.
@cindex @code{NUL} characters
+@findex libiconv
Utilities reading files should not drop NUL characters, or any other
nonprinting characters @emph{including those with codes above 0177}.
The only sensible exceptions would be utilities specifically intended
-for interface to certain types of terminals or printers
-that can't handle those characters.
-Whenever possible, try to make programs work properly with
-sequences of bytes that represent multibyte characters, using encodings
-such as UTF-8 and others.
+for interface to certain types of terminals or printers that can't
+handle those characters. Whenever possible, try to make programs work
+properly with sequences of bytes that represent multibyte characters;
+UTF-8 is the most important.
@cindex error messages
-Check every system call for an error return, unless you know you wish to
-ignore errors. Include the system error text (from @code{perror} or
-equivalent) in @emph{every} error message resulting from a failing
-system call, as well as the name of the file if any and the name of the
-utility. Just ``cannot open foo.c'' or ``stat failed'' is not
-sufficient.
+Check every system call for an error return, unless you know you wish
+to ignore errors. Include the system error text (from @code{perror},
+@code{strerror}, or equivalent) in @emph{every} error message
+resulting from a failing system call, as well as the name of the file
+if any and the name of the utility. Just ``cannot open foo.c'' or
+``stat failed'' is not sufficient.
@cindex @code{malloc} return value
@cindex memory allocation failure
@noindent
Line numbers should start from 1 at the beginning of the file, and
-column numbers should start from 1 at the beginning of the line. (Both
-of these conventions are chosen for compatibility.) Calculate column
-numbers assuming that space and all ASCII printing characters have
-equal width, and assuming tab stops every 8 columns.
+column numbers should start from 1 at the beginning of the line.
+(Both of these conventions are chosen for compatibility.) Calculate
+column numbers assuming that space and all ASCII printing characters
+have equal width, and assuming tab stops every 8 columns. For
+non-ASCII characters, Unicode character widths should be used when in
+a UTF-8 locale; GNU libc and GNU gnulib provide suitable
+@code{wcwidth} functions.
The error message can also give both the starting and ending positions
of the erroneous text. There are several formats so that you can
@pindex valgrind
@cindex memory leak
-Memory leak detectors such as @command{valgrind} can be useful, but
+Memory analysis tools such as @command{valgrind} can be useful, but
don't complicate a program merely to avoid their false alarms. For
example, if memory is used until just before a process exits, don't
-free it simply to silence a leak detector.
+free it simply to silence such a tool.
+
@node File Usage
@section File Usage
* System Functions:: Portability and ``standard'' library functions.
* Internationalization:: Techniques for internationalization.
* Character Set:: Use ASCII by default.
-* Quote Characters:: Use `...' in the C locale.
+* Quote Characters:: Use "..." or '...' in the C locale.
* Mmap:: How you can safely use @code{mmap}.
@end menu
around each string that might need translation---like this:
@example
-printf (gettext ("Processing file `%s'..."));
+printf (gettext ("Processing file '%s'..."), file);
@end example
@noindent
This permits GNU gettext to replace the string @code{"Processing file
-`%s'..."} with a translated version.
+'%s'..."} with a translated version.
Once a program uses gettext, please make a point of writing calls to
@code{gettext} when you add new strings that call for translation.
the application domain. For example, if source code deals with the
French Revolutionary calendar, it is OK if its literal strings contain
accented characters in month names like ``Flor@'eal''. Also, it is OK
-to use non-ASCII characters to represent proper names of contributors in
-change logs (@pxref{Change Logs}).
+(but not required) to use non-ASCII characters to represent proper
+names of contributors in change logs (@pxref{Change Logs}).
-If you need to use non-ASCII characters, you should normally stick with
-one encoding, as one cannot in general mix encodings reliably.
+If you need to use non-ASCII characters, you should normally stick
+with one encoding, certainly within a single file. UTF-8 is likely to
+be the best choice.
@node Quote Characters
@cindex quote characters
@cindex locale-specific quote characters
@cindex left quote
+@cindex right quote
+@cindex opening quote
+@cindex single quote
+@cindex double quote
@cindex grave accent
+@set txicodequoteundirected
+@set txicodequotebacktick
-In the C locale, GNU programs should stick to plain ASCII for quotation
-characters in messages to users: preferably 0x60 (@samp{`}) for left
-quotes and 0x27 (@samp{'}) for right quotes. It is ok, but not
-required, to use locale-specific quotes in other locales.
+In the C locale, the output of GNU programs should stick to plain
+ASCII for quotation characters in messages to users: preferably 0x22
+(@samp{"}) or 0x27 (@samp{'}) for both opening and closing quotes.
+Although GNU programs traditionally used 0x60 (@samp{`}) for opening
+and 0x27 (@samp{'}) for closing quotes, nowadays quotes @samp{`like
+this'} are typically rendered asymmetrically, so quoting @samp{"like
+this"} or @samp{'like this'} typically looks better.
-The @uref{http://www.gnu.org/software/gnulib/, Gnulib} @code{quote} and
-@code{quotearg} modules provide a reasonably straightforward way to
-support locale-specific quote characters, as well as taking care of
-other issues, such as quoting a filename that itself contains a quote
-character. See the Gnulib documentation for usage details.
+It is ok, but not required, for GNU programs to generate
+locale-specific quotes in non-C locales. For example:
-In any case, the documentation for your program should clearly specify
-how it does quoting, if different than the preferred method of @samp{`}
-and @samp{'}. This is especially important if the output of your
-program is ever likely to be parsed by another program.
+@example
+printf (gettext ("Processing file '%s'..."), file);
+@end example
-Quotation characters are a difficult area in the computing world at
-this time: there are no true left or right quote characters in Latin1;
-the @samp{`} character we use was standardized there as a grave
-accent. Moreover, Latin1 is still not universally usable.
+@noindent
+Here, a French translation might cause @code{gettext} to return the
+string @code{"Traitement de fichier
+@guilsinglleft{}@tie{}%s@tie{}@guilsinglright{}..."}, yielding quotes
+more appropriate for a French locale.
+
+Sometimes a program may need to use opening and closing quotes
+directly. By convention, @code{gettext} translates the string
+@samp{"`"} to the opening quote and the string @samp{"'"} to the
+closing quote, and a program can use these translations. Generally,
+though, it is better to translate quote characters in the context of
+longer strings.
-Unicode contains the unambiguous quote characters required, and its
-common encoding UTF-8 is upward compatible with Latin1. However,
-Unicode and UTF-8 are not universally well-supported, either.
+If the output of your program is ever likely to be parsed by another
+program, it is good to provide an option that makes this parsing
+reliable. For example, you could escape special characters using
+conventions from the C language or the Bourne shell. See for example
+the option @option{--quoting-style} of GNU @code{ls}.
-This may change over the next few years, and then we will revisit
-this.
+@clear txicodequoteundirected
+@clear txicodequotebacktick
@node Mmap
The reason this precaution is needed is that the GNU kernel (the HURD)
provides a user-extensible file system, in which there can be many
-different kinds of ``ordinary files.'' Many of them support
+different kinds of ``ordinary files''. Many of them support
@code{mmap}, but some do not. It is important to make programs handle
all these kinds of files.
+
@node Documentation
@chapter Documenting Programs
@cindex documentation
@example
* keyboard.c (menu_bar_items, tool_bar_items)
-(Fexecute_extended_command): Deal with `keymap' property.
+(Fexecute_extended_command): Deal with 'keymap' property.
@end example
When you install someone else's changes, put the contributor's name in
@cindex conditional changes, and change logs
@cindex change logs, conditional changes
-C programs often contain compile-time @code{#if} conditionals. Many
-changes are conditional; sometimes you add a new definition which is
-entirely contained in a conditional. It is very useful to indicate in
-the change log the conditions for which the change applies.
+Source files can often contain code that is conditional to build-time
+or static conditions. For example, C programs can contain
+compile-time @code{#if} conditionals; programs implemented in
+interpreted languages can contain module imports of function
+definitions that are only performed for certain versions of the
+interpreter; and Automake @file{Makefile.am} files can contain
+variable definitions or target declarations that are only to be
+considered if a configure-time Automake conditional is true.
-Our convention for indicating conditional changes is to use square
-brackets around the name of the condition.
+Many changes are conditional as well: sometimes you add a new variable,
+or function, or even a new program or library, which is entirely
+dependent on a build-time condition. It is useful to indicate
+in the change log the conditions for which a change applies.
-Here is a simple example, describing a change which is conditional but
-does not have a function or entity name associated with it:
+Our convention for indicating conditional changes is to use
+@emph{square brackets around the name of the condition}.
+
+Conditional changes can happen in numerous scenarios and with many
+variations, so here are some examples to help clarify. This first
+example describes changes in C, Perl, and Python files which are
+conditional but do not have an associated function or entity name:
@example
-* xterm.c [SOLARIS2]: Include string.h.
+* xterm.c [SOLARIS2]: Include <string.h>.
+* FilePath.pm [$^O eq 'VMS']: Import the VMS::Feature module.
+* framework.py [sys.version_info < (2, 6)]: Make "with" statement
+ available by importing it from __future__,
+ to support also python 2.5.
@end example
-Here is an entry describing a new definition which is entirely
-conditional. This new definition for the macro @code{FRAME_WINDOW_P} is
-used only when @code{HAVE_X_WINDOWS} is defined:
+Our other examples will for simplicity be limited to C, as the minor
+changes necessary to adapt them to other languages should be
+self-evident.
+
+Next, here is an entry describing a new definition which is entirely
+conditional: the C macro @code{FRAME_WINDOW_P} is defined (and used)
+only when the macro @code{HAVE_X_WINDOWS} is defined:
@example
* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
@end example
-Here is an entry for a change within the function @code{init_display},
-whose definition as a whole is unconditional, but the changes themselves
-are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
+Next, an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes
+themselves are contained in a @samp{#ifdef HAVE_LIBNCURSES}
+conditional:
@example
* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
@end example
-Here is an entry for a change that takes affect only when
+Finally, here is an entry for a change that takes effect only when
a certain macro is @emph{not} defined:
@example
@file{COPYING}. If the GNU LGPL is used, it should be in a file called
@file{COPYING.LESSER}.
-Naturally, all the source files must be in the distribution. It is okay
-to include non-source files in the distribution, provided they are
-up-to-date and machine-independent, so that building the distribution
-normally will never modify them. We commonly include non-source files
-produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+Naturally, all the source files must be in the distribution. It is
+okay to include non-source files in the distribution along with the
+source files they are generated from, provided they are up-to-date
+with the source they are made from, and machine-independent, so that
+normal building of the distribution will never modify them. We
+commonly include non-source files produced by Autoconf, Automake,
+Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
unnecessary dependencies between our distributions, so that users can
install whichever packages they want to install.
scope of what a software distribution needs to include.
Referring to a web site that describes or recommends a non-free
-program is promoting that program, so please do not make links (or
+program is promoting that program, so please do not make links to (or
mention by name) web sites that contain such material. This policy is
relevant particularly for the web pages for a GNU package.
projects / gnulib.git / blobdiff