GDB C Coding Standards

GDB follows the GNU Coding Standards. 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.

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.

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;

Column limits

There is a 74 soft limit and 80 hard limit for everything (source files, ChangeLogs, etc.) except for things like .exp files where we try to keep things under 80 but some lines are just long and best left as is.

soft = "stay within the limit unless you have a reasonable reason to exceed, and we're not nitpicky on what reasonable is"

hard = "do not exceed unless you just cannot do otherwise, and while there are exceptions, we are quite nitpicky on this one"

ref: https://sourceware.org/ml/gdb-patches/2014-01/msg00216.html

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.)

Exceptionally, */ can be put at a separate line if the comment is ended with an example, an output or a code snippet:

/* Arguments of complex T where T is one of the types float or
   double get treated as if they are implemented as:

struct complexT
{
  T real;
  T imag;
};

*/

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.

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.

Try to avoid complex macros. But, if you have to use a macro, make sure that the macro expansion is properly parenthesized.

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) {}

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.

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.

Include Files

All .c files under gdb/gdbserver/ must include server.h as their first non-comment line.

All other .c files under gdb/ must include defs.h as their first non-comment line.

The config.h headers for gdb and gnulib are included by common-defs.h. common-defs.h is included by both defs.h and server.h. No other file should include common-defs.h or the two config.h headers.

No .h file should include defs.h or server.h.

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. Exception: Do not include common-defs.h or the two config.h headers.

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: Do not include defs.h, server.h, common-defs.h or the two config.h headers.

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

In the above, "should" should really be "shall", but exceptions are possible if justified.