Next: Misc Guidelines, Previous: Support Libraries, Up: Top

## 16 Coding Standards

### 16.1 gdb C Coding Standards

gdb follows the GNU coding standards, as described in `etc/standards.texi`. This file is also available for anonymous FTP from GNU archive sites. gdb takes a strict interpretation of the standard; in general, when the GNU standard recommends a practice but does not require it, gdb requires it.

gdb follows an additional set of coding standards specific to gdb, as described in the following sections.

#### 16.1.1 ISO C

gdb assumes an ISO/IEC 9899:1990 (a.k.a. ISO C90) compliant compiler.

gdb does not assume an ISO C or POSIX compliant C library.

#### 16.1.2 Formatting

The standard GNU recommendations for formatting must be followed strictly. Any gdb-specific deviation from GNU recomendations is described below.

A function declaration should not have its name in column zero. A function definition should have its name in column zero.

         /* Declaration */
         static void foo (void);
         /* Definition */
         void
         foo (void)
         {
         }

Pragmatics: This simplifies scripting. Function definitions can be found using ‘`^function-name`’.

There must be a space between a function or macro name and the opening parenthesis of its argument list (except for macro definitions, as required by C). There must not be a space after an open paren/bracket or before a close paren/bracket.

While additional whitespace is generally helpful for reading, do not use more than one blank line to separate blocks, and avoid adding whitespace after the end of a program line (as of 1/99, some 600 lines had whitespace after the semicolon). Excess whitespace causes difficulties for `diff` and `patch` utilities.

Pointers are declared using the traditional K&R C style:

         void *foo;

and not:

         void * foo;
         void* foo;

In addition, whitespace around casts and unary operators should follow the following guidelines:

Use... | ...instead of |
`!x` | `! x`
`~x` | `~ x`
`-x` | `- x` | (unary minus)
`(foo) x` | `(foo)x` | (cast)
`*x` | `* x` | (pointer dereference)

Any two or more lines in code should be wrapped in braces, even if they are comments, as they look like separate statements:

         if (i)
           {
             /* Return success.  */
             return 0;
           }

and not:

         if (i)
           /* Return success.  */
           return 0;

#### 16.1.3 Comments

The standard GNU requirements on comments must be followed strictly.

Block comments must appear in the following form, with no `/*`- or `*/`-only lines, and no leading `*`:

         /* Wait for control to return from inferior to debugger.  If inferior
            gets a signal, we may decide to start it up again instead of
            returning.  That is why there is a loop in this function.  When
            this function actually returns it means the inferior should be left
            stopped and gdb should read more commands.  */

(Note that this format is encouraged by Emacs; tabbing for a multi-line comment works correctly, and `M-q` fills the block consistently.)

Put a blank line between the block comments preceding function or variable definitions, and the definition itself.

In general, put function-body comments on lines by themselves, rather than trying to fit them into the 20 characters left at the end of a line, since either the comment or the code will inevitably get longer than will fit, and then somebody will have to move it anyhow.

#### 16.1.4 C Usage

Code must not depend on the sizes of C data types, the format of the host's floating point numbers, the alignment of anything, or the order of evaluation of expressions.

Use functions freely. There are only a handful of compute-bound areas in gdb that might be affected by the overhead of a function call, mainly in symbol reading. Most of gdb's performance is limited by the target interface (whether serial line or system call).

However, use functions with moderation. A thousand one-line functions are just as hard to understand as a single thousand-line function.

Macros are bad, M'kay. (But if you have to use a macro, make sure that the macro arguments are protected with parentheses.)

Declarations like ‘`struct foo *`’ should be used in preference to declarations like ‘`typedef struct foo { ... } *foo_ptr`’.

Zero constant (`0`) is not interchangeable with a null pointer constant (`NULL`) anywhere. gcc does not give a warning for such interchange. Specifically:

incorrect | `if (pointervar) {}`
incorrect | `if (!pointervar) {}`
incorrect | `if (pointervar != 0) {}`
incorrect | `if (pointervar == 0) {}`
correct | `if (pointervar != NULL) {}`
correct | `if (pointervar == NULL) {}`

#### 16.1.5 Function Prototypes

Prototypes must be used when both declaring and defining a function. Prototypes for gdb functions must include both the argument type and name, with the name matching that used in the actual function definition.

All external functions should have a declaration in a header file that callers include, that declaration should use the `extern` modifier. The only exception concerns `_initialize_*` functions, which must be external so that `init.c` construction works, but shouldn't be visible to random source files.

Where a source file needs a forward declaration of a static function, that declaration must appear in a block near the top of the source file.

#### 16.1.6 File Names

Any file used when building the core of gdb must be in lower case. Any file used when building the core of gdb must be 8.3 unique. These requirements apply to both source and generated files.

Pragmatics: The core of gdb must be buildable on many platforms including DJGPP and MacOS/HFS. Every time an unfriendly file is introduced to the build process both `Makefile.in` and `configure.in` need to be modified accordingly. Compare the convoluted conversion process needed to transform `COPYING` into `copying.c` with the conversion needed to transform `version.in` into `version.c`.

Any file non 8.3 compliant file (that is not used when building the core of gdb) must be added to `gdb/config/djgpp/fnchange.lst`.

Pragmatics: This is clearly a compromise.

When gdb has a local version of a system header file (ex `string.h`) the file name based on the POSIX header prefixed with `gdb_` (`gdb_string.h`). These headers should be relatively independent: they should use only macros defined by `configure`, the compiler, or the host; they should include only system headers; they should refer only to system types. They may be shared between multiple programs, e.g. gdb and gdbserver.

For other files ‘`-`’ is used as the separator.

#### 16.1.7 Include Files

A `.c` file should include `defs.h` first.

A `.c` file should directly include the `.h` file of every declaration and/or definition it directly refers to. It cannot rely on indirect inclusion.

A `.h` file should directly include the `.h` file of every declaration and/or definition it directly refers to. It cannot rely on indirect inclusion. Exception: The file `defs.h` does not need to be directly included.

An external declaration should only appear in one include file.

An external declaration should never appear in a `.c` file. Exception: a declaration for the `_initialize` function that pacifies `-Wmissing-declaration`.

A `typedef` definition should only appear in one include file.

An opaque `struct` declaration can appear in multiple `.h` files. Where possible, a `.h` file should use an opaque `struct` declaration instead of an include.

All `.h` files should be wrapped in:

         #ifndef INCLUDE_FILE_NAME_H
         #define INCLUDE_FILE_NAME_H
         header body
         #endif

### 16.2 gdb Python Coding Standards

gdb follows the published `Python` coding standards in `PEP008`.

In addition, the guidelines in the Google Python Style Guide are also followed where they do not conflict with `PEP008`.

#### 16.2.1 gdb-specific exceptions

There are a few exceptions to the published standards. They exist mainly for consistency with the `C` standards.

- Use `FIXME` instead of `TODO`.