Joel's (unofficial) Coding Style Cheat-Sheet

An Important Introduction to this Document

The coding style used in GDB is fairly detailed. It follows mostly the GNU Coding Standards, with many rules added on top, some of them documented in the GDB Internals Manual (yes, they should all be documented in the gdbint manual, please consider helping by sending patches).

The purpose of this page is not to create an exhaustive nor authoritative list of all the little rules that govern the style of development used in GDB. Rather, it is intended to be used as a quick cheat-sheet with small examples that can be quickly accessed when needed. This information is provided as part of this Wiki in the hope that it might be useful to other developers.

This document is currently very very incomplete, and will be updated as I stumble on various rules that I cannot seem to remember. Anyone should feel free to update this document as well.

Formatting the Code

Maximum line length


It is recommended to limit the size of any line to 70 characters. This limit is only a guideline, so feel free to go beyond that limit a little bit if you think it helps readability. There is, however, a hard limit of 80 characters.

Personal note: After some fiddling, 70 characters still seems kind of low to me, and I think that 74 characters, similar to what is recommended for the ChangeLogs, might be a good guideline

Reference: http://www.sourceware.org/ml/gdb-patches/2011-01/msg00035.html

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

Empty line between local declarations and first statement


static void
do_fclose_cleanup (void *arg)
{
  FILE *file = arg;

  fclose (file);
}

Documenting your Code

Document Every Subprogram


Ideally, every subprogram should 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.  */

There seems to be a historical exception for the subprograms that are meant to be used as gdbarch, target_ops (etc) "methods", where developers omit to provide a description of what these subprogram do. This is acceptable too, but a quick comment like the one below does not cost much, and helps immediately understanding the purpose of the subprogram. I personally strongly recommend this practice.

/* 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. I strongly recommend this practice.

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

None: JoelsCodingStyleCheatSheet (last edited 2012-01-18 12:56:10 by brobecke)

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