Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:coding_style_guidelines

OpenTag Official Coding Style Guidelines

OpenTag coding guidelines include the Base Guidelines, the Style Guidelines, and the Performance Guidelines. The Style Guidelines (here) are pretty loose: they are enforced just to promote uniformity, readability, and maintainability. With OpenTag, performance always comes before style.

General Themes

  • Never, ever use C++. Doing so is grounds for banishment.
  • Use Doxygen markup wherever possible.
  • Write comments to your code: 25-50% of the text should be comments. If you do not think this level of commenting is necessary, you are not writing tight enough code (see performance guidelines).
  • Indent blocks of C code using 4 spaces.
  • Indent blocks of preprocessor code using 4 spaces, but keep the # at the rail.
  • Using C “goto's” is fine, even encouraged, but in moderation only (use your judgement).
  • Keep code relatively flat: that is, avoid extensive nested C brackets if you can.
  • Bit twiddling is encouraged… but leave comments telling us what it is doing.
  • Observe official code and do things the same way.

Comments, and Doxygen Usage

Descriptive comments shall be put into Doxygen markup. Incidentally, Doxygen markup is quite similar to javadocs and Qt documenting markup. The Javadocs style markup is preferred. To learn more about how to use Doxygen, check the doxygen manual (linked above) and use the existing OpenTag code as an example.

Inline Comments

C99 supports inline comments. Most other languages also do. Shown below are some inline comments for C.

// This is a normal inline comment in C
// Use these inside .c files to describe implementation notes that you don't want Doxygen to see.

/// This is a doxygen inline comment, for C.
/// Doxygen will parse these comments when you run the code through doxygen
/// Use these inside .c files to describe how a function is architected

Traditional Block Comments

C has supported block comments for as long as it has been around. C block comments look like: /* */. Traditional Block comments like this should never be used for actual comments in OpenTag. They should be used only for commenting-out blocks of experimental or legacy code.

Doxygen Block Comments

Doxygen Block Comments are like C block comments except they have some additional requirements.

/** Here is a Doxygen Block Comment.
  * Notice that it has two stars (**) after the slash (/).
  * Also notice that it has single stars indented under the second star.
  * A Doxygen comment ends like a normal block comment
  */

These doxygen block comments should be used with Doxygen markup in .h files to describe function prototypes, data types, and anything else that deserves commenting. They may also be used in .c files to do the same things. They should not be used within .c files, however, to document code implementations (the inline comments should be used for this).

Syntax Manipulation

C is really just text, but there are some conventions that shall be upheld in order to keep the code nice-looking.

Most Important Requirements

The most important requirement is: write your C in a similar style to what is there already! If this is not descriptive enough, here is a list of specific requirements for your C syntax.

Use Unix line breaks and UTF-8 text formatting

Unix line breaks are “LF” or “\n”. UTF-8 is a common type of text formatting. Most text editors support these.

Use Four spaces to indent code blocks

Anytime you go into a new scope or write a new preprocessor conditional, you must indent with four spaces. Tabs (“\t”) must not be used. Here is an example below (this should be simple enough):

void new_function(ot_int param1) {
    ot_int var1;        // notice that this is four spaces indented
    
    var1 = some_other_function(param1);
    
    if (var1 == 0) {    // here is another scope, so indent again
        var1 = yet_another_function(param1); 
    }
    
    return var1;
}
Align assignment expressions on 4-space tab boundaries

You will want to setup your text editor to automate tab conversion into spaces, because blocks of assignment expressions must have aligned equal signs. OpenTag might be the only codebase where this is practiced, but it makes the code look especially nice. Here's an example below (from /OTlib/network_M2.c):

m2np.header.fr_info    |= M2_FRINFO_ENADDR;
m2np.header.fr_info    |= (session->netstate >> 4) & 0x01;
m2np.header.fr_info    ^= 0x01;
m2np.header.fr_info    |= nack;
m2np.header.addr_ctl    = addressing;
m2np.header.addr_ctl   |= session->flags & 0x3F;

// |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
// Above are the tab boundaries.  Notice that the equal signs are aligned after a tab boundary.
// When using operators with the equal sign, the operator should be behind the tab boundary.

Encouraged Program Organization

Placeholder

Encouraged Programming Techniques

Placeholder

opentag/coding_style_guidelines.txt · Last modified: 2012/03/09 04:29 by jpnorair