<h2>Coding Guidelines</h2>

1. Coding Styles

Follow existing code when in doubt.

(1) Braces

- Put starting brace on the same line, not on a new line:

  if (something) {
  }

(2) Indentations

- No tabs. Only two spaces.
- Namespaces don't introduce indentations:

  namespace N1 { namespace N2 {
  class StillStartFromBeginning {
  };
  }}

- Function parameter indentations:

  void foo(int param1,
           int param2) {
  }

(3) Column Widths

- No more than 80 characters on a line.
- Vertically align coding if possible, but this is optional.

  int         m_num;
  std::string m_str;

(4) Conciseness

- Allow short if statements:

  if (...) one-liner;

- But no one-liner on 2nd line like this:

  if (...)
    one-liner;

- When possible, fit one function into one screen-full. Or, no long functions.

(5) Naming

- Class instance members start with "<b>m_</b>", unless trivial class/struct.
- Class static members start with "<b>s_</b>".
- Class instance methods use <b>camelCase</b>.
- Global functions use <b>small_underscore_small</b>() style.
- Enums start with <b>UpperCase</b>.

(6) Headers

- Never put "using namespace;" or other namespace exposures in header files.
- Try to keep one class one file, unless trivial classes or sub-classes.
- Try to keep class name consistent with file name so people can find them.
- Avoid function bodies in header files, unless absolutely necessary.

(7) Implementation Files

- Encourage static classes or functions that don't get exposed in headers.
- Have "namespace HPHP {" at top, instead of adding "HPHP::" to all functions.
- Logically group code into blocks with "/////////" separators.

(8) License Info

- run "php license.php" from bin/, and it will automatically add license info.

2. Library Dependencies

(1) Utility Library

util/ is at very bottom of the ladder. It may not depend on anything other
than external libraries. Therefore, if it includes anything runtime/, it's
wrong.

(2) Core Runtime Library

runtime/base and runtime/eval depend on util/. Since there may be file name conflicts,
ALWAYS use full include paths starting after hphp/.

(3) Extension Library

runtime/ext should theoretically strictly depend on runtime/base. We have messed up
some part of it, and we will clean them up. Please do NOT introduce more
violations.

(4) Generated Code

Generated code provides some functions, for example invoke(), that's referenced
by runtime/base and runtime/ext. We will come up with a solution to resolve this, maybe
by some raw pointers initialization routines. We want generated code to be on
top of the hierarchy after the modification.

3. Checkins and Unit Testing

(1) make fast_tests

Or simply "make" from hphp/. This is a set of tests that have to pass for every
checkin.

(2) make slow_tests

This normally runs for hours. Best to run them overnight. This set of tests is
required to pass for every checkin that changes fundamental code generations.

(3) avoid TestCodeRun if possible

Normally we prefer writing extension unit tests in TestExtSomething, because
we can then easiy run a valgrind command to check memory problems. TestCodeRun
is the last resort for things that are related to code generation, so they are
hard to test otherwise.
