Joel's (unofficial) Coding Style Cheat-Sheet
Contents
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;