Naming conventions
------------------

directory - lowercase (directory)
filename - corresponding class name without prefix (Filename)
class - upper camel case (ClassName)
member function - upper camel case (memberFunction)
member variable - snake case with trailing underscore (member_variable_)
                  Trailing underscore prevents conflict with accessor 
                  member function name.
function - lower camel case (functionName)
variable - snake case
comments - use capitalized sentences that end with periods

C++ code files should use a .cc file extension
C++ header files should use a .hh file extension

Use pragmas to protect headers from being read more than once instead of
ifdef/define.

  #pragma once

In general it is better to for class variables to use pointers to
objects of other classes rather than embedding the instance directly.
This only requires that the class be declared rather than defined,
many times breaking a dependency on another header file. 

Header files that define the classes of a sub-directory allow other
headers to have pointers to the objects without pulling in the details
of the class definitions.  These headers are named "DirectoryClass.hh"
where Directory is the capitalized name of the sub-directory.  

Place comments describing public functions and classes in header files
rather than code files because a consumer is more likely to have
access to the header and that is the first place they will look.

The return type of a function should be on the line before the
function name.  Arguments should be on separate lines to make it easier
to remove or add them without having to reformat the lines as they
change length.

return_type 
function(type1 arg1,
         type2 arg2)
{
}

Functions should be less than one screen long.  Break long functions
up into smaller ones.  Lines should be less than 90 characters long.

Avoid assignments inside `if'-conditions.  For example, don't write
this:

     if ((foo = (char *) malloc (sizeof *foo)) == 0)
       fatal ("virtual memory exhausted");

instead, write this:

     foo = (char *) malloc (sizeof *foo);
     if (foo == nullptr)
       fatal ("virtual memory exhausted");


Use braces around if/for bodies that are more than one line.
IE, 
  if (pred)
    for (int i = 0; i < len; i++) {  // this body should be in {}'s
       ...
    }

Add a default clause to all switches calling switchCaseNotHandled:

  switch (type) {
  case edge_interconnect:
    ...
  default:
    switchCaseNotHandled();
  }

Put return types for functions on the line before the function name:

 Cell *
 Library::findCell(char *name)
 {
  ...
 }

Class member functions should be grouped in public, protected and then
private order.

 class Frob
 {
 public:
 protected:
 private:

 friend class Frobulator;
 }

Don't declare class variables as const.  It means any downstream code
that accesses the member cannot modify it, which is overly
restrictive.

Avoid using [] to lookup a map value because it creates a key/null value
pair if the lookup fails.  Use map::find or sta::Map::findKey instead.

Avoid nested classes/enums because SWIG has trouble with them.

Regression Tests
................

Tests are run with the tcl script test/regression:

Usage: regression [-help] [-threads threads] [-valgrind] [-report_stats] tests...
  -threads max|integer - number of threads to use
  -valgrind - run valgrind (linux memory checker)
  -report_stats - report run time and memory
  Wildcarding for test names is supported (enclose in "'s)

Tests log files and results are in test/results. The result/test.log
is compared to test.ok to determine if a test passes.

Test scripts are written in tcl and live in the /test directory.
Compress large liberty, verilog, and spef, files and use existing
libraries to prevent repository bloat.

The test script should use a one line comment at the beginning of the
file so head -1 can show what it is for. Use file names to roughly
group regressions and use numeric suffixes to distinguish them.

The script test/save_ok saves a test/results/<test>.log to test/<test>.okfile.