Page History

...

2.2 Prefix and Directory Structure changes

For 2In the v2.2 we would like to change the prefix:
INK_/ink_/ink
to
TS_/ts_/ts. We are also looking to cleanup filenames, directory structure and other global style issues. See this page for additional detailsrelease 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.

...

#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;
}

...

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.

...

• -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)

...

• -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)

...