Coding Style

Overview

Code indentation and formatting was completely standardized prior to open sourcing the Apache Traffic Server code. Command line tool indent did most of the heavy lifting.

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

2.2 Prefix and Directory Structure changes

In the v2.2 release of Apache Traffic Server, we made some changes to prefixes, and directory structure. Some of this work is still undergoing, see this page for additional details. The most important part of these changes is the semantics of the prefix name spaces:

Public APIs (ts/ts.h, ts/experimental.h etc.)

The prefix to use for these include files and underlying code in e.g. InkAPI.cc is one of

TS or TS_
ts

In addition, none of these methods, struct names or definitions should be used in the core itself, other than the actual API implementations (InkAPI.cc etc.).

Internal code

For all other code that's internal, the prefix should be one of

ATS or ATS_
ats or ats_
INK or INK_
ink or ink_

No new code / functionality should be added using the ink/INK prefix. Long term, we will migrate these into the ats/ATS prefix.

Header files

In most subsystems, header files are named with a P_ or I_ prefix. P_ files should contain any types and definitions that are private to the subsystem, while the public interface should be contained in a I_-prefixed header.

Sample Code

This document relies on code samples which are below to demonstrate most of the rules used on the Apache Traffic Server project.

sample.cc

#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
    void _helpers() { _foo++; }

    int _count;			/// if there is something special to say
    int _totalCount;
  protected:
    void _anotherHelper() { _foo++; }
    int _foo;
  };
}


/**
 * @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 Formatting

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 formatting rules are mainly defaults from emacs, except for the indentation, so hitting TAB to indent the code in emacs will work well.

Emacs

The corresponding .emacs settings for our style is

(c-add-style "trafficserver"
         '((inclass . ++)
           (defun-block-intro . ++)
           (statement-block-intro . ++)
           (substatement . ++)
           (brace-list-intro . ++)
           (statement-case-intro . ++)
           (inextern-lang . 0)
           ))
(setq-default indent-tabs-mode nil)

Vim / vi

For .vimrc, this style is

set tabstop=2
set softtabstop=2
set shiftwidth=2
set expandtab
set textwidth=120

Using indent

There is a .indent.pro file in the top level of the source tree for Traffic Server. This will be used automaticly when invoking indent from the top level directory.

# running indent from the top level directory on the file proxy/Main.cc
$ indent proxy/Main.cc

Below is a manually way of specifying the options we use.

# 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 (GoodClassName)

Methods

Use camel case for method names with the first charter being lower case (goodMethodName)
Prepend '_' to the beginning of private or protected methods

Member Variables

Prepend '_' to the beginning of the private or protected member variable to distinguish it from other variable

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

XXX comments

Example of XXX:

  // XXX Hazardous code! We should find a way to make
  //     it more secure