Version 5 (modified by Gabriele Pohl, 4 years ago) (diff)

Some hints from Christian Franke on coding style

Coding Styleguide

Table of Contents

  1. Comments
  2. Some Hints

Comments

Doxygen generates our sourcecode documentation pages automatically by reading the sourcecode. If you set a block with C++ comment lines, where each line starts with an additional slash, the text will be shown in the doxygen generated docs. Note that a blank line ends a documentation block. You may add two blocks, a first one with a brief description and a second with an extended description for a class, struct or function.

/// SAT support.
/// Implements ATA by tunnelling through SCSI.

class sat_device

Use in line comment style to add explanation on defines and variables. A comment starting with three slashes, will appear in doxygen. Comments that start with only two slashes, will be invisible there.

// ATA ONLY
bool sct_erc_set;                       // set SCT ERC to:
unsigned short sct_erc_readtime;        // ERC read time (deciseconds)
unsigned short sct_erc_writetime;       // ERC write time (deciseconds)

unsigned char curr_pending_id;          // ID of current pending sector count, 0 if none
unsigned char offl_pending_id;          // ID of offline uncorrectable sector count, 0 if none

Some Hints

A snippet cut out of a mail from Christian Franke on developers list..

Due to its long history, many contributors and late move from C to C++, smartmontools is in fact a mixture of different coding styles.

In my recent additions I used (or tried to use) the following for new code:

Naming:
lowercase_underline_lowercase (like C++ std::)

Indentation:
2 Blanks, no tab characters

No extra indentation level for {...} blocks

No extra line for '{' except for the function body.

Lokal variables:
C++/C99 declaration statements: First use=declaration=initialization
(I really dislike traditional C style with all decls at the beginning of a block :-)

Null pointers:
"Stroustrup Style": 0 instead of NULL,
(T *)0 if needed or compiler check is desired.

Checks in boolean style: if (p) ; if (!p) ;

In comments: "nullptr" (forward compatible to C++0x :-)

Exceptions:
Avoid any try/catch blocks if possible, use RAII instead