Coding Style

This document described the coding style for the Apache Traffic Server project. The document is still evolving, but all contributors and committers are encourage to read this before contributing patches. And as usual, additions and edits to this document is appreciated, to assure that we all share the same coding style. For major changes to the style, a discussion should be opened on the dev@ mailing before changed here.

Overview

Code

Overview

The code indentation and formatting was completely standardized before prior to open sourcing the Apache Traffic Server code. The command 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.

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 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.

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

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

• -bap - blank line after every procedure body

  Code Block
  int foo() { puts("Hi"); } int bar() { puts("Hello"); }

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

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

• -nbc - no blank lines after commas

  Code Block
  int a, b, c

• -br - braces on the same line and the conditional

  Code Block
  if (x > 0) { --x; }

• -bls - braces on separate lines for structs and classes (different from K&R, same as GNU)

  Code Block
  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 '}'

  Code Block
  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

  Code Block
  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

  Code Block
  foo = (int) bar;

• -di2 - indentation of declarations on separate lines (different then K&R, increased to 2)

  Code Block
  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

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

• -npcs - no space after function call names

  Code Block
  foo(bar);

• -nprs - no space after parentheses

  Code Block
  foo((x - 1));

• -npsl - don't break procedure type

  Code Block
  int foo(char *s) { }

• -saf - space after each for

  Code Block
  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

  Code Block
  int x;

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

The public (API) headers 

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. Adhering to these rules is important, the goal is to be able to easily distinguish public from private APIs. In the past, we've had several cases where public APIs were used in the private code implementation, and this is a bad idea for both performance and functionality.

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.

Indentation

We have changed from the previous indentation rules, to rely completely on clang-format. The style is mostly the same as it was before, which means:

• 2-space indentation (never tabs)
• 132-character wide lines
• A clang-format based primarily on the Mozilla formatting. But, note that we have our own .clang-format in the top-level of the source tree.

The easiest way to format the code is to simply run

$ make clang-format

You can also explicitly format one (or several) source files with clang-format directly. Make sure you run it from the top-level directory, which has the necessary .clang-format configuration file. E.g.

$ clang-format -i proxy/logging/LogAccessHttp.cc

Vertical whitespace

No more than 1 adjacent empty line (clang-format enforces this). Leave a blank line after the closing branch when you have the same indentation level (clang-format sometimes messes this up).

You should have this :

void
foo(...)
{
  if (...) {
  }
 
  if (...) {
  }
}
 
void
bar(...)
{
  ...
}

clang-format binary and configuration

You must use the same clang-format binary as everyone else is. This is unfortunate, but is a side effect of how the clang-format team manages their code. You can download the current version, from April 13th 2018. Alternatively, you can build your own version from the clang / llvm source tree, but the tar-ball above includes binaries for both Linux and OS X. You have to copy either of these into somewhere your $PATH will locate, and rename it to just clang format. E.g.

$ tar xf clang-format-20180413.tar.bz2
$ sudo mv clang-format/clang-format.linux /usr/local/bin/clang-format

In addition to the binaries, there is a git script as well as en Emacs mode for clang-format.

Naming conventions

Classes and Structures

• Upper case for the first character of the name
• Use camel case (GoodClassName)

Methods

• Use STL style underscored lower case (<nop>GoodClassName)names for method names, (e.g. find_if).
• Predicates should use a prefix of "is_" or "has_" to check for a specific propery (e.g. is_valid).
• Use "this→" when calling other methods in the same class, to distinguish from free functions.

Member Variables

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

Comments

TODO comments

Example of comment TODO:

  // TODO handle case for negative config value

...

• 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

Notice the format:

• the XXX is all capitalized
• there is no colon or dash char after XXX
• there is no period at the end
• description is short (70 chars or less if possible) and helpful
• the XXX is used to warn other programmers of problematic or misguiding code.

no break comments

When your case will fall through, please add the no break comment with other more detialed comments at the end of the code block.
Example of no break:

    switch (*cur) {
    case ']' : // address close
      n_colon = MAX_COLON - 1;
      /* no break */
      /* fall through until ... */
    case ':' : // track colons, fail if too many.

That will help use understand the codes when someone may mistake that as bug. And be more nice to Eclipse CDT code analysis tool.