Coding Style

Overview

There are many different coding styles (indentation, formating, naming conventions) used in the Traffic Server code base and can sometimes distracting. It is best to agree on one standard even if having to compromise on a style you have become to accustomed to.

This document will describe the indentation, formating, doxygen comments, class naming, and naming conventions to use.

Sample Code

Instead of describing how to format to begin with, here is a sample below that demonstrates most of these rules.

#include <iostream>

using namespace std;

namespace ts
{
  /**
* @brief Demonstrates how to format code
* This class demonstrates to developers how we should structure code
   */
  class Counter
  {
  public:
    Counter():_count(0), _totalCount(0) { }

    /**
  * @brief Increments the count by one or an optional value
  * @param delta The amount to increment the count, default is 1
     */
    void increment(int delta = 1) {
      _count += delta;
    }
    /**
  * @brief Returns the count value
  * @return Count value
     */
    int getCount() const {      // try to use const as much as possible
      return _count;
    }

  private:			// try to hide data
    int _count;			/// if there is something special to say
    int _totalCount;
  };
}


/**
 * @brief This is the main function for the program
 */
int main()
{
  ts::Counter x;
  if (x.getCount() == 0) {
    x.increment();
  } else {
    // make sure to always use braces for conditionals
  }

  // increment the counter 10 times
  for (int i = 0; i < 10; ++i) {
    x.increment();
  }

  cout << x.getCount() << endl;
}

Indentation and Formating

This style is mostly K&R. Using the GNU indent command line tool as a definition of the K&R style, below is described in detail what options make up the -kr option for the tool and how this style differs. It is also worth noting that most of these formating rules are mainly defaults from emacs, except for the indentation, so hitting TAB to indent the code in emacs will work well.

Using indent

# use indent with the following commands
$ alias indent='indent -nut -nbad -bap -nbbo -nbc -br -bls -ce -ci2 -cli0 -cs -d0 -di2 -nfc1 -nfca -hnl -i2 -ip0 -l120 -lp -npcs -nprs -psl -saf -sai -saw -nsc -nsob -nss'
$ indent foo.cc

The -kr option or "common style" is described as:
-nbad -bap -bbo -nbc -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0
-cp33 -cs -d0 -di1 -nfc1 -nfca -hnl -i4 -ip0 -l75 -lp -npcs
-nprs -npsl -saf -sai -saw -nsc -nsob -ns

The code sample above can be closely formated by using the following options. Because of the number of variations of how code can be structured, indent will give a close and workable solution.
-nbad -bap -nbbo -nbc -br -bls -ce -ci2 -cli0
-cs -d0 -di2 -nfc1 -nfca -hnl -i2 -ip0 -l120 -lp -npcs
-nprs -npsl -saf -sai -saw -nsc -nsob -nss

Below describes each option of K&R and how the modified list of options differ from it. To sum up the major differences, comment structure is ignored mostly to work well with doxygen and indentation is changed from 4 spaces to 2 spaces.

-nut - No tabs in the source (for the love of god, don't put tabs in source code)

-nbad - no blank lines after declarations

char *foo;
char *bar;
/* no blank line above */
char *baz;

-bap - blank line after every procedure body

int foo() {
  puts("Hi");         
}

int bar() {
  puts("Hello");
}

-nbbo - break long lines after the boolean operators && and || (different from K&R and GNU)

if (cache_sm.cache_write_vc == NULL && 
    t_state.cache_info.write_lock_state == HttpTransact::CACHE_WL_INIT)

-nbc - no blank lines after commas
```
int a, b, c
```

-br - braces on the same line and the conditional
```
if (x > 0) {
  --x;
}
```

-bls - braces on separate lines for structs and classes (different from K&R, same as GNU)
```
struct foo
{
  int x;
};
```

-c33 & -cd33 - comments to the right of code start at column 33 (removed, only in K&R)

-ncdb - (removed, only in K&R)

-ce - if-then-else construct to "cuddle up" to the immediately preceding '}'
```
if (x > 0) {
  --x;
} else {
  cout << "hello world";
}
```

-ci2 - continuation indentation of 2 spaces (different then K&R, reduced to 2 spaces)

-cli0 - number of space3s that case labels should be indented to the right of the switch statement
```
switch (i) {
case 0:
  break;
default:
  break;     
}
```

-cp33 - comments on #else and #endif statements on column 33 (removed, only in K&R)

-cs - space after cast
```
foo = (int) bar;
```

-di2 - indentation of declarations on separate lines (different then K&R, increased to 2)
```
int x,
  y;
```

-nfc1 & -nfca - don't format any comments

-hnl - prefer to break long lines at the position of the newlines

-i2 - indent level (different then K&R, decreased from 4 to 2)

-ip0 - parameter indentation

-l120 - break long lines at 120 columns

-lp - indentation for continuation of parameters

p1 = first_procedure(second_procedure (p2, p3),
                     third_procedure (p4, p5));

-npcs - no space after function call names
```
foo(bar);
```

-nprs - no space after parentheses
```
foo((x - 1));
```

-npsl - don't break procedure type
```
int foo(char *s) {

}
```

-saf - space after each for

for (int i = 10; i > 0; --i) {
  // do something
}

-sai - space after each if

-saw - space after each while

-nsc - don't but '' at the left of comments *(removed, only in K&R)

-nsob - don't remove optional blank lines

-nss - don't put a space before the semicolon
```
int x;
```

Naming conventions

Classes and Structures

Upper case for the first character of the name
Use camel case (<nop>GoodClassName)

Member Variables

Prepend '_' at to the beginning of the member variable to distinguish it from other variables

Comments

TODO comments

Example of comment TODO:

  // TODO handle case for negative config value

Notice the format:

the TODO is all capitalized
first letter of TODO message does not need to be upper-case
there is no colon or dash char after TODO
there is no period at the end
description is short (70 chars or less if possible) and helpful
the TODO message describes an action that needs to be performed in the future

Space shortcuts

Page tree