GDB C/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.

Contents

  1. GDB C/C++ Coding Standards
    1. Formatting Your Code
      1. Function Definitions: Function Name at Column Zero
      2. Whitespaces
      3. Column limits
      4. Loop with empty body
      5. Indentation of lambdas as parameters
      6. Code indentation
    2. Documenting Your Code
      1. Document Every Subprogram
      2. Document every global/static entity
      3. Block Comment Formatting
      4. Blank Line After Block Comment Preceding Variable Definitions
      5. Prefer Function-Body Comments On Lines By Themselves
      6. Empty line between subprogram description and the subprogram implementation
    3. C++ Usage
      1. C++ dialect
      2. When is GDB going to start requiring C++NN ?
      3. C++-specific coding conventions
      4. Disallowed Assumptions
      5. Use of Functions
      6. Avoid Complex Macros
      7. Comparison With nullptr And Zero
      8. Function Prototypes
    4. File Names
      1. Include Files

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. Excess whitespace causes difficulties for diff and patch utilities.

Pointers and references are declared like this: 

void *foo;
int &bar;

and not: 

void * foo;
void* foo;
int & bar;
int& bar;

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

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 an 80 columns limit for source files 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.

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

Loop with empty body

While and for loops with empty body should use a semi-colon on the following line: 

while (p++ != NULL)
  ;

for (p = str; p != NULL; p++)
  ;

Indentation of lambdas as parameters

For for-each like functions which accept a lambda, the body of the lambda is indented as if it was a for loop's body: 

for_each_thread ([] (thread_info *thread)
  {
    /* Lambda body.  */
  });

Similarly, when a function has exactly one lambda argument, and it is the last argument of the call, the lambda body is indented as a code block: 

iterate_over_lwps (scope_ptid, [=] (struct lwp_info *info)
  {
    /* Lambda body.  */
  });

For the cases where we multiple argument are lambdas, or when the lambda isn't the last argument, the lambda is indented like other parameters: 

expand_symtabs_matching (nullptr, lookup_name, nullptr,
                         [&] (compunit_symtab *symtab)
                           {
                             add_symtab_completions (symtab,
                                                     tracker, mode, lookup_name,
                                                     sym_text, word, code);
                             return true;
                           },
                         SEARCH_GLOBAL_BLOCK | SEARCH_STATIC_BLOCK,
                         ALL_DOMAIN);

For a discussion about those rules, see https://sourceware.org/pipermail/gdb-patches/2022-June/190457.html.

Code indentation

Lines should be indented with a mix of tabs and spaces. 8 spaces should be replaced with Tab. Vim users could add the following to their ~/.vimrc: 

set autoindent tabstop=8 shiftwidth=2

Note that indentation increases by 2 and {} get their own indentation level.

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.

Static functions are documented where implemented. Functions with a declaration in a header file are documented where declared, and the implementation must have a comment referring to the header: 

  /* See foo.h.  */

  void
  do_foo ()
  {
    ...
  }

For functions 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" gdbarch 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

Put function-body comments on lines by themselves, not at the end of a line with code.

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:

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, prefer static inline functions. But, if you have to use a macro, make sure that the macro expansion is properly parenthesized.

Comparison With nullptr And Zero

When checking for a null pointer, perform an explicit comparison with nullptr:

Similarly for numbers:

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 .cc files under gdbserver/ must include server.h as their first non-comment line.

All .c and .cc files under gdbsupport/ 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 or .cc 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:

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.

None: Internals GDB-C-Coding-Standards (last edited 2023-01-25 13:23:25 by AlexandraHajkova)

All content (C) 2008 Free Software Foundation. For terms of use, redistribution, and modification, please see the WikiLicense page.