Subversion Repositories or1k

START-INFO-DIR-ENTRY

START-INFO-DIR-ENTRY

* Standards: (standards).        GNU coding standards.

* Standards: (standards).        GNU coding standards.

END-INFO-DIR-ENTRY

END-INFO-DIR-ENTRY

Accepting Contributions

Accepting Contributions

=======================

=======================

   If someone else sends you a piece of code to add to the program you

   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

are working on, we need legal papers to use it--the same sort of legal

a program must sign some sort of legal papers in order for us to have

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.

clear title to the program.  The main author alone is not enough.

   So, before adding in any contributions from other people, please tell

   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

us, so we can arrange to get the papers.  Then wait until we tell you

File: standards.info,  Node: Semantics,  Next: Libraries,  Up: Program Behavior

File: standards.info,  Node: Semantics,  Next: Libraries,  Up: Program Behavior

Writing Robust Programs

Writing Robust Programs

=======================

=======================

structure, including file names, lines, files, and symbols, by

structure, including file names, lines, files, and symbols, by

allocating all data structures dynamically.  In most Unix utilities,

allocating all data structures dynamically.  In most Unix utilities,

"long lines are silently truncated".  This is not acceptable in a GNU

"long lines are silently truncated".  This is not acceptable in a GNU

utility.

utility.

   Utilities reading files should not drop NUL characters, or any other

   Utilities reading files should not drop NUL characters, or any other

only sensible exceptions would be utilities specifically intended for

only sensible exceptions would be utilities specifically intended for

interface to certain types of printers that can't handle those

interface to certain types of printers that can't handle those

characters.

characters.

   Check every system call for an error return, unless you know you

   Check every system call for an error return, unless you know you

wish to ignore errors.  Include the system error text (from `perror' or

wish to ignore errors.  Include the system error text (from `perror' or

call, as well as the name of the file if any and the name of the

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.

utility.  Just "cannot open foo.c" or "stat failed" is not sufficient.

   Check every call to `malloc' or `realloc' to see if it returned

   Check every call to `malloc' or `realloc' to see if it returned

zero.  Check `realloc' even if you are making the block smaller; in a

zero.  Check `realloc' even if you are making the block smaller; in a

comments in the source.  The relevant data will be in variables, which

comments in the source.  The relevant data will be in variables, which

are easy to examine with the debugger, so there is no point moving them

are easy to examine with the debugger, so there is no point moving them

elsewhere.

elsewhere.

   Do not use a count of errors as the exit status for a program.

   Do not use a count of errors as the exit status for a program.

(0 through 255).  A single run of the program might have 256 errors; if

(0 through 255).  A single run of the program might have 256 errors; if

you try to return 256 as the exit status, the parent process will see 0

you try to return 256 as the exit status, the parent process will see 0

as the status, and it will appear that the program succeeded.

as the status, and it will appear that the program succeeded.

   If you make temporary files, check the `TMPDIR' environment

   If you make temporary files, check the `TMPDIR' environment

     version number proper starts after the last space.  In addition,

     version number proper starts after the last space.  In addition,

     it contains the canonical name for this program, in this format:

     it contains the canonical name for this program, in this format:

          GNU Emacs 19.30

          GNU Emacs 19.30

     from `argv[0]'.  The idea is to state the standard or canonical

     from `argv[0]'.  The idea is to state the standard or canonical

     name for the program, not its file name.  There are other ways to

     name for the program, not its file name.  There are other ways to

     find out the precise file name where a command is found in `PATH'.

     find out the precise file name where a command is found in `PATH'.

     If the program is a subsidiary part of a larger package, mention

     If the program is a subsidiary part of a larger package, mention

* Comments::                    Commenting Your Work

* Comments::                    Commenting Your Work

* Syntactic Conventions::       Clean Use of C Constructs

* Syntactic Conventions::       Clean Use of C Constructs

* Names::                       Naming Variables and Functions

* Names::                       Naming Variables and Functions

* System Portability::          Portability between different operating systems

* System Portability::          Portability between different operating systems

* CPU Portability::             Supporting the range of CPU types

* CPU Portability::             Supporting the range of CPU types

* Internationalization::        Techniques for internationalization

* Internationalization::        Techniques for internationalization

* Mmap::                        How you can safely use `mmap'.

* Mmap::                        How you can safely use `mmap'.

File: standards.info,  Node: Formatting,  Next: Comments,  Up: Writing C

File: standards.info,  Node: Formatting,  Next: Comments,  Up: Writing C

        zero means continue them.  */

        zero means continue them.  */

     int truncate_lines;

     int truncate_lines;

   Every `#endif' should have a comment, except in the case of short

   Every `#endif' should have a comment, except in the case of short

conditionals (just a few lines) that are not nested.  The comment should

conditionals (just a few lines) that are not nested.  The comment should

     #ifdef foo

     #ifdef foo

       ...

       ...

     #else /* not foo */

     #else /* not foo */

       ...

       ...

       fprintf (stderr, "error: ");

       fprintf (stderr, "error: ");

       fprintf (stderr, s, a1, a2, a3);

       fprintf (stderr, s, a1, a2, a3);

     }

     }

In practice, this works on all machines, and it is much simpler than any

In practice, this works on all machines, and it is much simpler than any

functions.

functions.

   However, avoid casting pointers to integers unless you really need

   However, avoid casting pointers to integers unless you really need

to.  These assumptions really reduce portability, and in most programs

to.  These assumptions really reduce portability, and in most programs

they are easy to avoid.  In the cases where casting pointers to

they are easy to avoid.  In the cases where casting pointers to

documented in one manual; but this does not mean each program should

documented in one manual; but this does not mean each program should

have its own manual.  That would be following the structure of the

have its own manual.  That would be following the structure of the

implementation, rather than the structure that helps the user

implementation, rather than the structure that helps the user

understand.

understand.

instead of a manual for `diff' and a manual for `diff3', we have one

instead of a manual for `diff' and a manual for `diff3', we have one

manual for "comparison of files" which covers both of those programs,

manual for "comparison of files" which covers both of those programs,

as well as `cmp'.  By documenting these programs together, we can make

as well as `cmp'.  By documenting these programs together, we can make

the whole subject clearer.

the whole subject clearer.

   That is not as hard as it first sounds.  Arrange each chapter as a

   That is not as hard as it first sounds.  Arrange each chapter as a

logical breakdown of its topic, but order the sections, and write their

logical breakdown of its topic, but order the sections, and write their

text, so that reading the chapter straight through makes sense.  Do

text, so that reading the chapter straight through makes sense.  Do

likewise when structuring the book into chapters, and when structuring a

likewise when structuring the book into chapters, and when structuring a

   If necessary, add extra chapters at the beginning of the manual which

   If necessary, add extra chapters at the beginning of the manual which

are purely tutorial and cover the basics of the subject.  These provide

are purely tutorial and cover the basics of the subject.  These provide

the framework for a beginner to understand the rest of the manual.  The

the framework for a beginner to understand the rest of the manual.  The

Bison manual provides a good example of how to do this.

Bison manual provides a good example of how to do this.

are contained in a `#ifdef HAVE_LIBNCURSES' conditional:

are contained in a `#ifdef HAVE_LIBNCURSES' conditional:

     * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.

     * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.

   Here is an entry for a change that takes affect only when a certain

   Here is an entry for a change that takes affect only when a certain

     (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.

     (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.

File: standards.info,  Node: Man Pages,  Next: Reading other Manuals,  Prev: Change Logs,  Up: Documentation

File: standards.info,  Node: Man Pages,  Next: Reading other Manuals,  Prev: Change Logs,  Up: Documentation

   The `configure' script must record the configuration options so that

   The `configure' script must record the configuration options so that

they affect compilation.

they affect compilation.

   One way to do this is to make a link from a standard name such as

   One way to do this is to make a link from a standard name such as

`config.h' to the proper configuration file for the chosen system.  If

`config.h' to the proper configuration file for the chosen system.  If

named `config.h'.  This is so that people won't be able to build the

named `config.h'.  This is so that people won't be able to build the

program without configuring it first.

program without configuring it first.

   Another thing that `configure' can do is to edit the Makefile.  If

   Another thing that `configure' can do is to edit the Makefile.  If

`Makefile'.  Instead, it should include a file `Makefile.in' which

`Makefile'.  Instead, it should include a file `Makefile.in' which

contains the input used for editing.  Once again, this is so that people

contains the input used for editing.  Once again, this is so that people

won't be able to build the program without configuring it first.

won't be able to build the program without configuring it first.

   If `configure' does write the `Makefile', then `Makefile' should

   If `configure' does write the `Makefile', then `Makefile' should

but we keep them because they are standard.) Use `CPPFLAGS' in any

but we keep them because they are standard.) Use `CPPFLAGS' in any

compilation command that runs the preprocessor, and use `LDFLAGS' in

compilation command that runs the preprocessor, and use `LDFLAGS' in

any compilation command that does linking as well as in any direct use

any compilation command that does linking as well as in any direct use

of `ld'.

of `ld'.

compilation of certain files, do not include them in `CFLAGS'.  Users

compilation of certain files, do not include them in `CFLAGS'.  Users

expect to be able to specify `CFLAGS' freely themselves.  Instead,

expect to be able to specify `CFLAGS' freely themselves.  Instead,

arrange to pass the necessary options to the C compiler independently

arrange to pass the necessary options to the C compiler independently

of `CFLAGS', by writing them explicitly in the compilation commands or

of `CFLAGS', by writing them explicitly in the compilation commands or

by defining an implicit rule, like this:

by defining an implicit rule, like this:

     ALL_CFLAGS = -I. $(CFLAGS)

     ALL_CFLAGS = -I. $(CFLAGS)

     .c.o:

     .c.o:

             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<

             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<

   Do include the `-g' option in `CFLAGS', because that is not

   Do include the `-g' option in `CFLAGS', because that is not

is only recommended.  If the package is set up so that it is compiled

is only recommended.  If the package is set up so that it is compiled

with GCC by default, then you might as well include `-O' in the default

with GCC by default, then you might as well include `-O' in the default

value of `CFLAGS' as well.

value of `CFLAGS' as well.

   Put `CFLAGS' last in the compilation command, after other variables

   Put `CFLAGS' last in the compilation command, after other variables

   A category line consists of a tab and a reference to a special Make

   A category line consists of a tab and a reference to a special Make

variable, plus an optional comment at the end.  There are three

variable, plus an optional comment at the end.  There are three

variables you can use, one for each category; the variable name

variables you can use, one for each category; the variable name

specifies the category.  Category lines are no-ops in ordinary execution

specifies the category.  Category lines are no-ops in ordinary execution

because these three Make variables are normally undefined (and you

because these three Make variables are normally undefined (and you

   Here are the three possible category lines, each with a comment that

   Here are the three possible category lines, each with a comment that

explains what it means:

explains what it means:

             $(PRE_INSTALL)     # Pre-install commands follow.

             $(PRE_INSTALL)     # Pre-install commands follow.

   Typically, a pre-uninstall command would be used for deleting entries

   Typically, a pre-uninstall command would be used for deleting entries

from the Info directory.

from the Info directory.

   If the `install' or `uninstall' target has any dependencies which

   If the `install' or `uninstall' target has any dependencies which

dependency's commands with a category line, and start the main target's

dependency's commands with a category line, and start the main target's

commands with a category line also.  This way, you can ensure that each

commands with a category line also.  This way, you can ensure that each

command is placed in the right category regardless of which of the

command is placed in the right category regardless of which of the

dependencies actually run.

dependencies actually run.

know what other files to get.

know what other files to get.

Tag Table:

Tag Table:

End Tag Table

End Tag Table