spot/HACKING

Bootstraping:
=============

Some files in SPOT's source tree are generated.  They are distributed
so that users do not need to tools to rebuild them, but we don't keep
all of them under CVS because it can generate lots of changes or
conflicts.

Here are the tools you need to bootstrap the CVS tree, or more
generally if you plan to regenerate some of the generated files.
 
  GNU Autoconf 2.57
  GNU Automake 1.7.3
  GNU Flex (the version probably doesn't matter much, we used 2.5.4)
  The CVS version of GNU Bison (called 1.875b at the time of writing)

Bootstrap the CVS tree by running

  autoreconf -vfi

and then go on with the usual 

  ./configure
  make

Coding conventions:
===================

Here are the conventions we follow in Spot, so that the code looks
homogeneous.

Comments
--------

  * The language to use is American.

  * When comments are sentences, they should start with a capital and
    end with a dot.  Dots that end sentences should be followed by two
    spaces (i.e., American typing convention), like in this paragraph.

Formating
---------

  * Braces on their own line.

  * Text within braces is two-space indented.

    {
      f(12);
      
    }

  * Anything after a control statement is two-space indented.  This
    includes braces.

    if (test)
      {
        f(123);
	while (test2)
	  g(456);
      }

  * Braces from function/structure/enum/classe/namespace definitions
    are not indented.

    class foo
    {
    public:
      Foo();
    protected:
      static int get_mumble();
    };

  * The above corresponds to the `gnu' indentation style under Emacs.
     
  * Put return types or linkage specifiers on their own line in
    function/method _definitions_ :

    static int
    Foo::get_mumble()
    {
      return 2;
    }

    This makes it easier to grep functions in the code.

    Function/method declarations can be put on one line.

  * Space before parentheses in control statements

    if (test)
      {
        do
	  {
	    something();
	  }
	while (0);
      }

  * No space before parentheses in function calls.
    (`some()->foo()->bar()' is far more readable than
    `some ()->foo ()->bar ()' is)

  * No space after opening or before closing parentheses, however
    put a space after commas (as in english).
    
    func(arg1, arg2, arg3);
   
  * No useless parentheses in return statements.

    return 2;    (not `return (2);')
    

  * Spaces around infix binary or ternary operators:

    2 + 2;
    a = b;
    a <<= (3 + 5) * 3 + f(67 + (really ? 45 : 0));
    
  * No space after prefix unary operators, or befor postfix unary operators:

    if (!test && y++ != 0)
      {
        ++x;
      }

  * When an expression spans over several lines, split it before
    operators.  If it's inside a parenthesis, the following lines
    should be 1-indented w.r.t. the opening parenthesis.

    if (foo_this_is_long && bar > win(x, y, z)
        && !remaining_condition)
      {
        ...
      }

  * If a line takes more than 80 columns, split it or rethink it.

  * Labels or case statements are left-indented by two spaces,
    without space before the `:'.
  
    if (something)
      {
      top:
        bar = foo();
        switch (something_else)
	  {
	  case first_case:
	    f();
	    break;
	  case second_case:
	    g();
	    break;
	  default:
	    goto top;
	  }
      }

Naming
======

  * Functions, methods, types, classes, etc. are named with lowercase
    letters, using an underscore to separate words.

      int compute_this_and_that();

      class this_is_a_class;
      
      typedef int int_array[];

    That is the style used in STL.

  * private members end with an underscore.

    class my_class
    {
    public:
      ...
      int get_val() const;
    private:
      int name_;
    };

  * Identifiers (even internal) starting with `_' are best avoided
    to limit clashes with system definitions.

  * Template arguments use capitalized name, with joined words.

    template <class T, int NumberOfThings>
    class foo
    {
      ...
    };

  * Enum mumblers also use capitalized name, with joined words.

  * C Macros are all uppercase.

  * Pointers and references are part of the type, and should be put
    near the type, not near the variable.

      int* p;        // not `int *p;'
      list& l;       // not `list &l;'
      void* magic(); // not `void *magic();'

  * Do not declare many variables on one line.
    Use
      int* p;
      int* q;
    instead of
      int *p, *q;
    The former declarations also allow you to describe each variable.

  * The include guard for src/somedir/foo.hh is
    SPOT_SOMEDIR_FOO_HH