1 This is Info file ../info/standards.info, produced by Makeinfo version
2 1.68 from the input file standards.texi.
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
9 Software Foundation, Inc.
11 Permission is granted to make and distribute verbatim copies of this
12 manual provided the copyright notice and this permission notice are
13 preserved on all copies.
15 Permission is granted to copy and distribute modified versions of
16 this manual under the conditions for verbatim copying, provided that
17 the entire resulting derived work is distributed under the terms of a
18 permission notice identical to this one.
20 Permission is granted to copy and distribute translations of this
21 manual into another language, under the above conditions for modified
22 versions, except that this permission notice may be stated in a
23 translation approved by the Free Software Foundation.
26 File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
31 Last updated 17 May 1996.
35 * Preface:: About the GNU Coding Standards
36 * Intellectual Property:: Keeping Free Software Free
37 * Design Advice:: General Program Design
38 * Program Behavior:: Program Behavior for All Programs
39 * Writing C:: Making The Best Use of C
40 * Documentation:: Documenting Programs
41 * Managing Releases:: The Release Process
44 File: standards.info, Node: Preface, Next: Intellectual Property, Prev: Top, Up: Top
46 About the GNU Coding Standards
47 ******************************
49 The GNU Coding Standards were written by Richard Stallman and other
50 GNU Project volunteers. Their purpose is to make the GNU system clean,
51 consistent, and easy to install. This document can also be read as a
52 guide to writing portable, robust and reliable programs. It focuses on
53 programs written in C, but many of the rules and principles are useful
54 even if you write in another programming language. The rules often
55 state reasons for writing in a certain way.
57 Corrections or suggestions regarding this document should be sent to
58 `gnu@prep.ai.mit.edu'. If you make a suggestion, please include a
59 suggested new wording for it; our time is limited. We prefer a context
60 diff to the `standards.texi' or `make-stds.texi' files, but if you
61 don't have those files, please mail your suggestion anyway.
63 This release of the GNU Coding Standards was last updated 17 May
67 File: standards.info, Node: Intellectual Property, Next: Design Advice, Prev: Preface, Up: Top
69 Keeping Free Software Free
70 **************************
72 This node discusses how you can make sure that GNU software remains
77 * Reading Non-Free Code:: Referring to Proprietary Programs
78 * Contributions:: Accepting Contributions
81 File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Intellectual Property
83 Referring to Proprietary Programs
84 =================================
86 Don't in any circumstances refer to Unix source code for or during
87 your work on GNU! (Or to any other proprietary programs.)
89 If you have a vague recollection of the internals of a Unix program,
90 this does not absolutely mean you can't write an imitation of it, but
91 do try to organize the imitation internally along different lines,
92 because this is likely to make the details of the Unix version
93 irrelevant and dissimilar to your results.
95 For example, Unix utilities were generally optimized to minimize
96 memory use; if you go for speed instead, your program will be very
97 different. You could keep the entire input file in core and scan it
98 there instead of using stdio. Use a smarter algorithm discovered more
99 recently than the Unix program. Eliminate use of temporary files. Do
100 it in one pass instead of two (we did this in the assembler).
102 Or, on the contrary, emphasize simplicity instead of speed. For some
103 applications, the speed of today's computers makes simpler algorithms
106 Or go for generality. For example, Unix programs often have static
107 tables or fixed-size strings, which make for arbitrary limits; use
108 dynamic allocation instead. Make sure your program handles NULs and
109 other funny characters in the input files. Add a programming language
110 for extensibility and write part of the program in that language.
112 Or turn some parts of the program into independently usable
113 libraries. Or use a simple garbage collector instead of tracking
114 precisely when to free memory, or use a new GNU facility such as
118 File: standards.info, Node: Contributions, Prev: Reading Non-Free Code, Up: Intellectual Property
120 Accepting Contributions
121 =======================
123 If someone else sends you a piece of code to add to the program you
124 are working on, we need legal papers to use it--the same sort of legal
125 papers we will need to get from you. *Each* significant contributor to
126 a program must sign some sort of legal papers in order for us to have
127 clear title to the program. The main author alone is not enough.
129 So, before adding in any contributions from other people, tell us so
130 we can arrange to get the papers. Then wait until we tell you that we
131 have received the signed papers, before you actually use the
134 This applies both before you release the program and afterward. If
135 you receive diffs to fix a bug, and they make significant changes, we
136 need legal papers for it.
138 You don't need papers for changes of a few lines here or there, since
139 they are not significant for copyright purposes. Also, you don't need
140 papers if all you get from the suggestion is some ideas, not actual code
141 which you use. For example, if you write a different solution to the
142 problem, you don't need to get papers.
144 We know this is frustrating; it's frustrating for us as well. But if
145 you don't wait, you are going out on a limb--for example, what if the
146 contributor's employer won't sign a disclaimer? You might have to take
149 The very worst thing is if you forget to tell us about the other
150 contributor. We could be very embarrassed in court some day as a
154 File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Intellectual Property, Up: Top
156 General Program Design
157 **********************
159 This node discusses some of the issues you should take into account
160 when designing your program.
164 * Compatibility:: Compatibility with other implementations
165 * Using Extensions:: Using non-standard features
166 * ANSI C:: Using ANSI C features
167 * Source Language:: Using languages other than C
170 File: standards.info, Node: Compatibility, Next: Using Extensions, Up: Design Advice
172 Compatibility with Other Implementations
173 ========================================
175 With occasional exceptions, utility programs and libraries for GNU
176 should be upward compatible with those in Berkeley Unix, and upward
177 compatible with ANSI C if ANSI C specifies their behavior, and upward
178 compatible with POSIX if POSIX specifies their behavior.
180 When these standards conflict, it is useful to offer compatibility
181 modes for each of them.
183 ANSI C and POSIX prohibit many kinds of extensions. Feel free to
184 make the extensions anyway, and include a `--ansi', `--posix', or
185 `--compatible' option to turn them off. However, if the extension has
186 a significant chance of breaking any real programs or scripts, then it
187 is not really upward compatible. Try to redesign its interface.
189 Many GNU programs suppress extensions that conflict with POSIX if the
190 environment variable `POSIXLY_CORRECT' is defined (even if it is
191 defined with a null value). Please make your program recognize this
192 variable if appropriate.
194 When a feature is used only by users (not by programs or command
195 files), and it is done poorly in Unix, feel free to replace it
196 completely with something totally different and better. (For example,
197 `vi' is replaced with Emacs.) But it is nice to offer a compatible
198 feature as well. (There is a free `vi' clone, so we offer it.)
200 Additional useful features not in Berkeley Unix are welcome.
201 Additional programs with no counterpart in Unix may be useful, but our
202 first priority is usually to duplicate what Unix already has.
205 File: standards.info, Node: Using Extensions, Next: ANSI C, Prev: Compatibility, Up: Design Advice
207 Using Non-standard Features
208 ===========================
210 Many GNU facilities that already exist support a number of convenient
211 extensions over the comparable Unix facilities. Whether to use these
212 extensions in implementing your program is a difficult question.
214 On the one hand, using the extensions can make a cleaner program.
215 On the other hand, people will not be able to build the program unless
216 the other GNU tools are available. This might cause the program to
217 work on fewer kinds of machines.
219 With some extensions, it might be easy to provide both alternatives.
220 For example, you can define functions with a "keyword" `INLINE' and
221 define that as a macro to expand into either `inline' or nothing,
222 depending on the compiler.
224 In general, perhaps it is best not to use the extensions if you can
225 straightforwardly do without them, but to use the extensions if they
226 are a big improvement.
228 An exception to this rule are the large, established programs (such
229 as Emacs) which run on a great variety of systems. Such programs would
230 be broken by use of GNU extensions.
232 Another exception is for programs that are used as part of
233 compilation: anything that must be compiled with other compilers in
234 order to bootstrap the GNU compilation facilities. If these require
235 the GNU compiler, then no one can compile them without having them
236 installed already. That would be no good.
239 File: standards.info, Node: ANSI C, Next: Source Language, Prev: Using Extensions, Up: Design Advice
241 ANSI C and pre-ANSI C
242 =====================
244 Do not ever use the "trigraph" feature of ANSI C.
246 ANSI C is widespread enough now that it is ok to write new programs
247 that use ANSI C features (and therefore will not work in non-ANSI
248 compilers). And if a program is already written in ANSI C, there's no
249 need to convert it to support non-ANSI compilers.
251 However, it is easy to support non-ANSI compilers in most programs,
252 so you might still consider doing so when you write a program. Instead
253 of writing function definitions in ANSI prototype form,
259 write the definition in pre-ANSI style like this,
266 and use a separate declaration to specify the argument prototype:
270 You need such a declaration anyway, in a header file, to get the
271 benefit of ANSI C prototypes in all the files where the function is
272 called. And once you have it, you lose nothing by writing the function
273 definition in the pre-ANSI style.
275 If you don't know non-ANSI C, there's no need to learn it; just
279 File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice
281 Using Languages Other Than C
282 ============================
284 Using a language other than C is like using a non-standard feature:
285 it will cause trouble for users. Even if GCC supports the other
286 language, users may find it inconvenient to have to install the
287 compiler for that other language in order to build your program. So
290 There are three exceptions for this rule:
292 * It is okay to use a special language if the same program contains
293 an interpreter for that language.
295 For example, if your program links with GUILE, it is ok to write
296 part of the program in Scheme or another language supported by
299 * It is okay to use another language in a tool specifically intended
300 for use with that language.
302 This is okay because the only people who want to build the tool
303 will be those who have installed the other language anyway.
305 * If an application is not of extremely widespread interest, then
306 perhaps it's not important if the application is inconvenient to
310 File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
312 Program Behavior for All Programs
313 *********************************
315 This node describes how to write robust software. It also describes
316 general standards for error messages, the command line interface, and
317 how libraries should behave.
321 * Semantics:: Writing robust programs
322 * Libraries:: Library behavior
323 * Errors:: Formatting error messages
324 * User Interfaces:: Standards for command line interfaces
325 * Memory Usage:: When and how to care about memory needs
328 File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior
330 Writing Robust Programs
331 =======================
333 Avoid arbitrary limits on the length or number of *any* data
334 structure, including file names, lines, files, and symbols, by
335 allocating all data structures dynamically. In most Unix utilities,
336 "long lines are silently truncated". This is not acceptable in a GNU
339 Utilities reading files should not drop NUL characters, or any other
340 nonprinting characters *including those with codes above 0177*. The
341 only sensible exceptions would be utilities specifically intended for
342 interface to certain types of printers that can't handle those
345 Check every system call for an error return, unless you know you
346 wish to ignore errors. Include the system error text (from `perror' or
347 equivalent) in *every* error message resulting from a failing system
348 call, as well as the name of the file if any and the name of the
349 utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
351 Check every call to `malloc' or `realloc' to see if it returned
352 zero. Check `realloc' even if you are making the block smaller; in a
353 system that rounds block sizes to a power of 2, `realloc' may get a
354 different block if you ask for less space.
356 In Unix, `realloc' can destroy the storage block if it returns zero.
357 GNU `realloc' does not have this bug: if it fails, the original block
358 is unchanged. Feel free to assume the bug is fixed. If you wish to
359 run your program on Unix, and wish to avoid lossage in this case, you
360 can use the GNU `malloc'.
362 You must expect `free' to alter the contents of the block that was
363 freed. Anything you want to fetch from the block, you must fetch before
366 If `malloc' fails in a noninteractive program, make that a fatal
367 error. In an interactive program (one that reads commands from the
368 user), it is better to abort the command and return to the command
369 reader loop. This allows the user to kill other processes to free up
370 virtual memory, and then try the command again.
372 Use `getopt_long' to decode arguments, unless the argument syntax
373 makes this unreasonable.
375 When static storage is to be written in during program execution, use
376 explicit C code to initialize it. Reserve C initialized declarations
377 for data that will not be changed.
379 Try to avoid low-level interfaces to obscure Unix data structures
380 (such as file directories, utmp, or the layout of kernel memory), since
381 these are less likely to work compatibly. If you need to find all the
382 files in a directory, use `readdir' or some other high-level interface.
383 These will be supported compatibly by GNU.
385 By default, the GNU system will provide the signal handling
386 functions of BSD and of POSIX. So GNU software should be written to use
389 In error checks that detect "impossible" conditions, just abort.
390 There is usually no point in printing any message. These checks
391 indicate the existence of bugs. Whoever wants to fix the bugs will have
392 to read the source code and run a debugger. So explain the problem with
393 comments in the source. The relevant data will be in variables, which
394 are easy to examine with the debugger, so there is no point moving them
397 Do not use a count of errors as the exit status for a program.
398 *That does not work*, because exit status values are limited to 8 bits
399 (0 through 255). A single run of the program might have 256 errors; if
400 you try to return 256 as the exit status, the parent process will see 0
401 as the status, and it will appear that the program succeeded.
403 If you make temporary files, check the `TMPDIR' environment
404 variable; if that variable is defined, use the specified directory
408 File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
413 Try to make library functions reentrant. If they need to do dynamic
414 storage allocation, at least try to avoid any nonreentrancy aside from
415 that of `malloc' itself.
417 Here are certain name conventions for libraries, to avoid name
420 Choose a name prefix for the library, more than two characters long.
421 All external function and variable names should start with this prefix.
422 In addition, there should only be one of these in any given library
423 member. This usually means putting each one in a separate source file.
425 An exception can be made when two external symbols are always used
426 together, so that no reasonable program could use one without the
427 other; then they can both go in the same file.
429 External symbols that are not documented entry points for the user
430 should have names beginning with `_'. They should also contain the
431 chosen name prefix for the library, to prevent collisions with other
432 libraries. These can go in the same files with user entry points if
435 Static functions and variables can be used as you like and need not
436 fit any naming convention.
439 File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
441 Formatting Error Messages
442 =========================
444 Error messages from compilers should look like this:
446 SOURCE-FILE-NAME:LINENO: MESSAGE
448 Error messages from other noninteractive programs should look like
451 PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
453 when there is an appropriate source file, or like this:
457 when there is no relevant source file.
459 In an interactive program (one that is reading commands from a
460 terminal), it is better not to include the program name in an error
461 message. The place to indicate which program is running is in the
462 prompt or with the screen layout. (When the same program runs with
463 input from a source other than a terminal, it is not interactive and
464 would do best to print error messages using the noninteractive style.)
466 The string MESSAGE should not begin with a capital letter when it
467 follows a program name and/or file name. Also, it should not end with
470 Error messages from interactive programs, and other messages such as
471 usage messages, should start with a capital letter. But they should not
475 File: standards.info, Node: User Interfaces, Next: Memory Usage, Prev: Errors, Up: Program Behavior
477 Standards for Command Line Interfaces
478 =====================================
480 Please don't make the behavior of a utility depend on the name used
481 to invoke it. It is useful sometimes to make a link to a utility with
482 a different name, and that should not change what it does.
484 Instead, use a run time option or a compilation switch or both to
485 select among the alternate behaviors.
487 Likewise, please don't make the behavior of the program depend on the
488 type of output device it is used with. Device independence is an
489 important principle of the system's design; do not compromise it merely
490 to save someone from typing an option now and then.
492 If you think one behavior is most useful when the output is to a
493 terminal, and another is most useful when the output is a file or a
494 pipe, then it is usually best to make the default behavior the one that
495 is useful with output to a terminal, and have an option for the other
498 Compatibility requires certain programs to depend on the type of
499 output device. It would be disastrous if `ls' or `sh' did not do so in
500 the way all users expect. In some of these cases, we supplement the
501 program with a preferred alternate version that does not depend on the
502 output device type. For example, we provide a `dir' program much like
503 `ls' except that its default output format is always multi-column
506 It is a good idea to follow the POSIX guidelines for the
507 command-line options of a program. The easiest way to do this is to use
508 `getopt' to parse them. Note that the GNU version of `getopt' will
509 normally permit options anywhere among the arguments unless the special
510 argument `--' is used. This is not what POSIX specifies; it is a GNU
513 Please define long-named options that are equivalent to the
514 single-letter Unix-style options. We hope to make GNU more user
515 friendly this way. This is easy to do with the GNU function
518 One of the advantages of long-named options is that they can be
519 consistent from program to program. For example, users should be able
520 to expect the "verbose" option of any GNU program which has one, to be
521 spelled precisely `--verbose'. To achieve this uniformity, look at the
522 table of common long-option names when you choose the option names for
523 your program. The table appears below.
525 If you use names not already in the table, please send
526 `gnu@prep.ai.mit.edu' a list of them, with their meanings, so we can
529 It is usually a good idea for file names given as ordinary arguments
530 to be input files only; any output files would be specified using
531 options (preferably `-o'). Even if you allow an output file name as an
532 ordinary argument for compatibility, try to provide a suitable option
533 as well. This will lead to more consistency among GNU utilities, so
534 that there are fewer idiosyncracies for users to remember.
536 Programs should support an option `--version' which prints the
537 program's version number on standard output and exits successfully, and
538 an option `--help' which prints option usage information on standard
539 output and exits successfully. These options should inhibit the normal
540 function of the command; they should do nothing except print the
541 requested information.
543 Here is the table of long options used by GNU programs.
549 `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
558 `-a' in `etags', `tee', `time'; `-r' in `tar'.
609 `-b' in `cpio' and `diff'.
615 Used in `cpio' and `tar'.
618 `-b' in `head' and `tail'.
624 Used in various programs to make output shorter.
627 `-c' in `head', `split', and `tail'.
636 Used in various programs to specify the directory to use.
639 `-c' in `chgrp' and `chown'.
648 `-c' in `su'; `-x' in GDB.
657 `-Z' in `tar' and `shar'.
669 `-W copyleft' in `gawk'.
672 `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
684 Used in `tar' and `cpio'.
696 `-d' in Make and `m4'; `-t' in Bison.
702 `-d' in Bison and `ctags'.
708 `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
726 Specify the directory to use, in various programs. In `ls', it
727 means to show directories themselves rather than their contents.
728 In `rm' and `ln', it means to not treat links to directories
755 `environment-overrides'
795 `-i' in `cpio'; `-x' in `tar'.
807 `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
838 `-f' in `cp', `ln', `mv', and `rm'.
844 Used in `ls', `time', and `ptx'.
868 `-z' in `tar' and `shar'.
874 `-h' in `objdump' and `recode'
880 Used to ask for brief usage information.
895 `-I' in `ls'; `-x' in `recode'.
907 `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
924 `ignore-matching-lines'
927 `ignore-space-change'
934 `-i' in `etags'; `-I' in `m4'.
943 `-i', `-l', and `-m' in Finger.
955 `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
974 `-k' in `du' and `ls'.
989 Used in `split', `head', and `tail'.
999 `-t' in `cpio'; `-l' in `recode'.
1014 No listing of which programs already use this; someone should
1015 check to see if any actually do and tell `gnu@prep.ai.mit.edu'.
1021 `-m' in `hello' and `uname'.
1060 `-m' in `install', `mkdir', and `mkfifo'.
1083 `no-character-count'
1141 Used in various programs to inhibit warnings.
1168 `-n' in `cpio' and `ls'.
1180 `-l' in `tar', `cp', and `du'.
1192 In various programs, specify the output file name.
1213 `-p' in `mkdir' and `rmdir'.
1225 `-c' in `cpio' and `tar'.
1237 Used in `tar' and `cp'.
1239 `preserve-environment'
1242 `preserve-modification-time'
1248 `preserve-permissions'
1282 Used in many programs to inhibit the usual output. *Please note:*
1283 every program accepting `--quiet' should accept `--silent' as a
1311 Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
1320 `-r' in `tac' and `etags'.
1337 `report-identical-files'
1344 `-r' in `ls' and `nm'.
1374 Used by `recode' to chose files or pipes for sequencing passes.
1388 `show-function-line'
1395 Used in many programs to inhibit the usual output. *Please note:*
1396 every program accepting `--silent' should accept `--quiet' as a
1406 `-W source' in `gawk'.
1430 Used in `tar' and `diff' to specify which file within a directory
1431 to start processing with.
1458 `-S' in `cp', `ln', `mv'.
1473 Used in GDB and `objdump'.
1482 `-t' in `expand' and `unexpand'.
1488 `-T' in `tput' and `ul'. `-t' in `wdiff'.
1497 Used in `ls' and `touch'.
1506 `-t' in Make, `ranlib', and `recode'.
1512 `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
1540 `-u' in `cp', `ctags', `mv', `tar'.
1543 Used in `gawk'; same as `--help'.
1552 Print more information about progress. Many programs support this.
1558 Print the version number.
1561 `-V' in `cp', `ln', `mv'.
1576 `-w' in `ls' and `ptx'.
1588 File: standards.info, Node: Memory Usage, Prev: User Interfaces, Up: Program Behavior
1593 If it typically uses just a few meg of memory, don't bother making
1594 any effort to reduce memory usage. For example, if it is impractical
1595 for other reasons to operate on files more than a few meg long, it is
1596 reasonable to read entire input files into core to operate on them.
1598 However, for programs such as `cat' or `tail', that can usefully
1599 operate on very large files, it is important to avoid using a technique
1600 that would artificially limit the size of files it can handle. If a
1601 program works by lines and could be applied to arbitrary user-supplied
1602 input files, it should keep only a line in memory, because this is not
1603 very hard and users will want to be able to operate on input files that
1604 are bigger than will fit in core all at once.
1606 If your program creates complicated data structures, just make them
1607 in core and give a fatal error if `malloc' returns zero.
1610 File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
1612 Making The Best Use of C
1613 ************************
1615 This node provides advice on how best to use the C language when
1616 writing GNU software.
1620 * Formatting:: Formatting Your Source Code
1621 * Comments:: Commenting Your Work
1622 * Syntactic Conventions:: Clean Use of C Constructs
1623 * Names:: Naming Variables and Functions
1624 * System Portability:: Portability between different operating systems
1625 * CPU Portability:: Supporting the range of CPU types
1626 * System Functions:: Portability and "standard" library functions
1627 * Internationalization:: Techniques for internationalization
1630 File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
1632 Formatting Your Source Code
1633 ===========================
1635 It is important to put the open-brace that starts the body of a C
1636 function in column zero, and avoid putting any other open-brace or
1637 open-parenthesis or open-bracket in column zero. Several tools look
1638 for open-braces in column zero to find the beginnings of C functions.
1639 These tools will not work on code not formatted that way.
1641 It is also important for function definitions to start the name of
1642 the function in column zero. This helps people to search for function
1643 definitions, and may also help certain tools recognize them. Thus, the
1644 proper format is this:
1647 concat (s1, s2) /* Name starts in column zero here */
1649 { /* Open brace in column zero here */
1653 or, if you want to use ANSI C, format the definition like this:
1656 concat (char *s1, char *s2)
1661 In ANSI C, if the arguments don't fit nicely on one line, split it
1665 lots_of_args (int an_integer, long a_long, short a_short,
1666 double a_double, float a_float)
1669 For the body of the function, we prefer code formatted like this:
1680 return ++x + bar ();
1683 We find it easier to read a program when it has spaces before the
1684 open-parentheses and after the commas. Especially after the commas.
1686 When you split an expression into multiple lines, split it before an
1687 operator, not after one. Here is the right way:
1689 if (foo_this_is_long && bar > win (x, y, z)
1690 && remaining_condition)
1692 Try to avoid having two operators of different precedence at the same
1693 level of indentation. For example, don't write this:
1695 mode = (inmode[j] == VOIDmode
1696 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
1697 ? outmode[j] : inmode[j]);
1699 Instead, use extra parentheses so that the indentation shows the
1702 mode = ((inmode[j] == VOIDmode
1703 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
1704 ? outmode[j] : inmode[j]);
1706 Insert extra parentheses so that Emacs will indent the code properly.
1707 For example, the following indentation looks nice if you do it by hand,
1708 but Emacs would mess it up:
1710 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
1711 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
1713 But adding a set of parentheses solves the problem:
1715 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
1716 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
1718 Format do-while statements like this:
1726 Please use formfeed characters (control-L) to divide the program into
1727 pages at logical places (but not within a function). It does not matter
1728 just how long the pages are, since they do not have to fit on a printed
1729 page. The formfeeds should appear alone on lines by themselves.
1732 File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
1734 Commenting Your Work
1735 ====================
1737 Every program should start with a comment saying briefly what it is
1738 for. Example: `fmt - filter for simple filling of text'.
1740 Please put a comment on each function saying what the function does,
1741 what sorts of arguments it gets, and what the possible values of
1742 arguments mean and are used for. It is not necessary to duplicate in
1743 words the meaning of the C argument declarations, if a C type is being
1744 used in its customary fashion. If there is anything nonstandard about
1745 its use (such as an argument of type `char *' which is really the
1746 address of the second character of a string, not the first), or any
1747 possible values that would not work the way one would expect (such as,
1748 that strings containing newlines are not guaranteed to work), be sure
1751 Also explain the significance of the return value, if there is one.
1753 Please put two spaces after the end of a sentence in your comments,
1754 so that the Emacs sentence commands will work. Also, please write
1755 complete sentences and capitalize the first word. If a lower-case
1756 identifier comes at the beginning of a sentence, don't capitalize it!
1757 Changing the spelling makes it a different identifier. If you don't
1758 like starting a sentence with a lower case letter, write the sentence
1759 differently (e.g., "The identifier lower-case is ...").
1761 The comment on a function is much clearer if you use the argument
1762 names to speak about the argument values. The variable name itself
1763 should be lower case, but write it in upper case when you are speaking
1764 about the value rather than the variable itself. Thus, "the inode
1765 number NODE_NUM" rather than "an inode".
1767 There is usually no purpose in restating the name of the function in
1768 the comment before it, because the reader can see that for himself.
1769 There might be an exception when the comment is so long that the
1770 function itself would be off the bottom of the screen.
1772 There should be a comment on each static variable as well, like this:
1774 /* Nonzero means truncate lines in the display;
1775 zero means continue them. */
1778 Every `#endif' should have a comment, except in the case of short
1779 conditionals (just a few lines) that are not nested. The comment should
1780 state the condition of the conditional that is ending, *including its
1781 sense*. `#else' should have a comment describing the condition *and
1782 sense* of the code that follows. For example:
1788 #endif /* not foo */
1790 but, by contrast, write the comments this way for a `#ifndef':
1799 File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
1801 Clean Use of C Constructs
1802 =========================
1804 Please explicitly declare all arguments to functions. Don't omit
1805 them just because they are `int's.
1807 Declarations of external functions and functions to appear later in
1808 the source file should all go in one place near the beginning of the
1809 file (somewhere before the first function definition in the file), or
1810 else should go in a header file. Don't put `extern' declarations inside
1813 It used to be common practice to use the same local variables (with
1814 names like `tem') over and over for different values within one
1815 function. Instead of doing this, it is better declare a separate local
1816 variable for each distinct purpose, and give it a name which is
1817 meaningful. This not only makes programs easier to understand, it also
1818 facilitates optimization by good compilers. You can also move the
1819 declaration of each local variable into the smallest scope that includes
1820 all its uses. This makes the program even cleaner.
1822 Don't use local variables or parameters that shadow global
1825 Don't declare multiple variables in one declaration that spans lines.
1826 Start a new declaration on each line, instead. For example, instead of
1841 (If they are global variables, each should have a comment preceding it
1844 When you have an `if'-`else' statement nested in another `if'
1845 statement, always put braces around the `if'-`else'. Thus, never write
1864 If you have an `if' statement nested inside of an `else' statement,
1865 either write `else if' on one line, like this,
1872 with its `then'-part indented like the preceding `then'-part, or write
1873 the nested `if' within braces like this:
1883 Don't declare both a structure tag and variables or typedefs in the
1884 same declaration. Instead, declare the structure tag separately and
1885 then use it to declare the variables or typedefs.
1887 Try to avoid assignments inside `if'-conditions. For example, don't
1890 if ((foo = (char *) malloc (sizeof *foo)) == 0)
1891 fatal ("virtual memory exhausted");
1893 instead, write this:
1895 foo = (char *) malloc (sizeof *foo);
1897 fatal ("virtual memory exhausted");
1899 Don't make the program ugly to placate `lint'. Please don't insert
1900 any casts to `void'. Zero without a cast is perfectly fine as a null
1901 pointer constant, except when calling a varargs function.
1904 File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
1906 Naming Variables and Functions
1907 ==============================
1909 Please use underscores to separate words in a name, so that the Emacs
1910 word commands can be useful within them. Stick to lower case; reserve
1911 upper case for macros and `enum' constants, and for name-prefixes that
1912 follow a uniform convention.
1914 For example, you should use names like `ignore_space_change_flag';
1915 don't use names like `iCantReadThis'.
1917 Variables that indicate whether command-line options have been
1918 specified should be named after the meaning of the option, not after
1919 the option-letter. A comment should state both the exact meaning of
1920 the option and its letter. For example,
1922 /* Ignore changes in horizontal whitespace (-b). */
1923 int ignore_space_change_flag;
1925 When you want to define names with constant integer values, use
1926 `enum' rather than `#define'. GDB knows about enumeration constants.
1928 Use file names of 14 characters or less, to avoid creating gratuitous
1929 problems on older System V systems. You can use the program `doschk'
1930 to test for this. `doschk' also tests for potential name conflicts if
1931 the files were loaded onto an MS-DOS file system--something you may or
1935 File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
1937 Portability between System Types
1938 ================================
1940 In the Unix world, "portability" refers to porting to different Unix
1941 versions. For a GNU program, this kind of portability is desirable, but
1944 The primary purpose of GNU software is to run on top of the GNU
1945 kernel, compiled with the GNU C compiler, on various types of CPU. The
1946 amount and kinds of variation among GNU systems on different CPUs will
1947 be comparable to the variation among Linux-based GNU systems or among
1948 BSD systems today. So the kinds of portability that are absolutely
1949 necessary are quite limited.
1951 But many users do run GNU software on non-GNU Unix or Unix-like
1952 systems. So supporting a variety of Unix-like systems is desirable,
1953 although not paramount.
1955 The easiest way to achieve portability to most Unix-like systems is
1956 to use Autoconf. It's unlikely that your program needs to know more
1957 information about the host platform than Autoconf can provide, simply
1958 because most of the programs that need such knowledge have already been
1961 Avoid using the format of semi-internal data bases (e.g.,
1962 directories) when there is a higher-level alternative (`readdir').
1964 As for systems that are not like Unix, such as MSDOS, Windows, the
1965 Macintosh, VMS, and MVS, supporting them is usually so much work that it
1966 is better if you don't.
1968 The planned GNU kernel is not finished yet, but you can tell which
1969 facilities it will provide by looking at the GNU C Library Manual. The
1970 GNU kernel is based on Mach, so the features of Mach will also be
1971 available. However, if you use Mach features, you'll probably have
1972 trouble debugging your program today.