Overview

There are many different coding styles (indentation, formating, naming conventions) used in the yts 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 yts
{
  /**
* @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()
{
  yts::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:

<verbatim class="example">
// TODO handle case for negative config value
</verbatim>

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