Putting cyrus-future code in CVS. Also, code style

[Bron Gondwana]

On Mon, Jun 28, 2010 at 11:59:54AM -0400, Matt Selsky wrote:
> We should document the rules for the prevalent style and put it in the wiki.  Who can do that? (time and access-wise)

Also, the file doc/internal/hacking in CVS should probably include the
rules.

Off the top of my head:

* spacing is 4 characters with soft tabs at 8 - mixed tabs and spaces
* char *foo not char* foo
* if (condition)
  for (i = 0; i < x; i++)
  while (foo) {
  - spaces after punctuation, not before.  Parantheses cuddle close.  Space
    between keyword and bracket
* braces are optional if meaning is clear
  if (foo)
    function();
  else
    other_function();
* function definitions are followed by a brace on a line by itself, all other
  braces are inline.  Return types are inline with function definition.
  void thing(int val)
  {
    if (thing) {
      do();
      stuff();
    }
  }
* goto is permitted within a function only
* generally, zero return is SUCCESS and integer return is an error code.

Anything else anyone want to add?

Oh yeah... there's something I really want to add.  Naming standards for
variables.  But that's a deep rabbit hole.  There are tools with names
like "the_box" for a mailbox which is called "mailbox" everywhere else.
Where possible I'd like to standardise that so the same patterns of code
look the same wherever they're used.  That's trickier though, and could
get quite long-winded.  What I would like to say is:

* DON'T EVER REUSE THE SAME VARIABLE FOR TWO DIFFERENT PURPOSES IN THE SAME
  FUNCTION.  IN FACT, DON'T REUSE THE SAME VARIABLE _NAME_ FOR DIFFERENT
  PURPOSES.  KTHXBYE.  (note: this doesn't apply to 'i', 'n', etc which are
  used in multiple loops.  It applies to using the same name for an absolute
  offset and a "within this mmap" offset though, and it also applies to
  using the same variable name for native order and network order numbers,
  which is where I've seen it a few times and been super frustrated!)
* use "const char *" where possible.
* let's figure out what we're doing with bit32 types - I've moved them into
  lib/util.h, so they're available everywhere.  Also, should create a bit64
  type for the same reason.
* use 'struct buf' for variable length strings (again, I just moved this in
  to lib/util.h and expanded the functions to deal with it)
* RAII where possible.
* Allocate and deallocate in a wrapper so you can use return with an error
  code without multiple lines of error handling between every single line
  of actual logic.
* if you find yourself passing the same multiple parameters through many
  functions, create a struct and populate that instead.

That all make sense?

Bron.