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.

Formatting Your Code

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

Function Definitions: Function Name at Column Zero

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.

Whitespaces

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

Documenting Your Code

The standard GNU requirements on comments must be followed strictly.

Document Every Subprogram

Every subprogram must be documented. The documentation should consist of a comment region, placed before the subprogram declaration or implementation.

Most of the time, the comment is placed just before the subprogram implementation, in the .c file. Sometimes, developers who write a new module with public API in a .h file, and associated implementation in a .c file, elect to document the public routines in the .h file. This makes it easy to consult the API, and is acceptable too.

/* Return the task number of the task whose ptid is PTID, or zero
   if the task could not be found.  */

For subprograms meant to be used as gdbarch, target_ops (etc) "methods", a one-line comment referencing the "method" being implemented is now required. While it does not cost must, it allows the function's behavior to be documented without repeating the corresponding's method's documentation. For instance:

/* The "cannot_store_register" target_ops method.  */

static int
ia64_hpux_cannot_store_register (struct gdbarch *gdbarch, int regnum)

Document every global/static entity

All entities that are not declared inside a subprogram block should be documented. This includes types and global constants. Try avoiding global variables as much as possible, as they usually cause all sorts of problems (you might need one instance of that global per inferior, for instance).

/* The maximum number of tasks known to the Ada runtime.  */
static const int MAX_NUMBER_OF_KNOWN_TASKS = 1000;

When you define a composite type such as a struct type, for instance, it is a really good idea to document each field/component individually.

/* We keep a cache of stack frames, each of which is a "struct
   frame_info".  The innermost one gets allocated (in [...].  */

struct frame_info
{
  /* Level of this frame.  The inner-most (youngest) frame is at level
     [...].  */
  int level;

  /* The frame's program space.  */
  struct program_space *pspace;

  /* The frame's address space.  */
  struct address_space *aspace;

  /* The frame's low-level unwinder and corresponding cache.  The
     low-level unwinder is responsible for unwinding register values
     for [...].  */
  void *prologue_cache;

Block Comment Formatting

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;
};

*/

Blank Line After Block Comment Preceding Variable Definitions

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

Prefer Function-Body Comments On Lines By Themselves

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.

Empty line between subprogram description and the subprogram implementation

There should be an empty line between the end of the comment describing a subprogram, and the subprogram itself.

/* Return the task number of the task whose ptid is PTID, or zero
   if the task could not be found.  */

int
ada_get_task_number (ptid_t ptid)

Note that this only applies to the case where the comment is placed besides the subprogram implementation (typically in a .c file). In the case of the documentation being placed next to the subprogram declaration, then the comment should be placed immediately before the declaration.

/* Return true if PTID represents a process id.  */
extern int ptid_is_pid (ptid_t ptid);

C++ Usage

C++ dialect

GDB assumes an ISO/IEC 14882:2011 (a.k.a. ISO C++11) compliant compiler. For example, GCC 4.8.1 or later.

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

When is GDB going to start requiring C++NN ?

Our general policy is to wait until the oldest compiler that supports C++NN is at least 3 years old.

Rationale: We want to ensure reasonably widespread compiler availability, to lower barrier of entry to GDB contributions, and to make it easy for users to easily build new GDB on currently supported stable distributions themselves. 3 years should be sufficient for latest stable releases of distributions to include a compiler for the standard, and/or for new compilers to appear as easily installable optional packages. Requiring everyone to build a compiler first before building GDB, which would happen if we required a too-new compiler, would cause too much inconvenience.

See the policy proposal and discussion here.

C++-specific coding conventions

GDB follows GCC's C++ coding conventions, diverging only on finer detail, as we find necessary.

See these documents, which have extensive detail:

• GCC's C++ Language Conventions (scroll down a bit)

• GCC Coding Conventions Rationale and Discussion

A point where we diverge is in permitting the use of C++ exceptions.

Disallowed Assumptions

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 of Functions

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.

Avoid Complex Macros

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

NULL Is Not Zero

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 .c files under gdb/common/, gdb/nat/ and gdb/target/ must include common-defs.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 either of the config.h headers. No file other than .c files under gdb/common/, gdb/nat/ and gdb/target/ should include common-defs.h.

No .h file should include defs.h, server.h or common-defs.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: no .c file should include any header included directly or indirectly from whichever of common-defs.h, defs.h or server.h that the .c file included as its first non-comment line.

All .c files must include the .h file of the same name if it exists as their second non-comment line, even if defs.h, server.h or common-defs.h already includes it. That is, include their corresponding interface header right after defs.h. Examples:

• infrun.c includes defs.h and then infrun.h.

• ptid.c includes ptid.h even though ptid.c includes common-defs.h which includes ptid.h.

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 any .h file included by whichever of common-defs.h, defs.h or server.h should be included by a .c file in the same directory as the .h file.

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 /* INCLUDE_FILE_NAME_H */

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