
On Ident and Coding style :

  Here are some coding rules that I think are important. Much of these
  come from my experience of debugging a 70K lines C project written by
  three distinct people, each with their own coding style. I just found that
  the code written with these rules tended to be larger but much, much,
  easier to read and understand. Of course, it's still a matter of taste.

  - huge amounts of newlines, which makes the code "airy". You may not find
    that too useful on a 25-lines text screen, but a real improvement when
    you print the whole code and try to read it from paper. It really speeds
    things up ( and should I remind you that paper is the ultimate debugger :)

  - Always for the "airy"-consious ;), spearate keywords and symbols
    with spaces, even < > = . Spacing seems less important if you use
    a syntax-hilighting editor, however just try to print the code and
    the difference will strike you.

    This includes spacing in the function calls. Suppressing them in text
    is welcome, though..

  - Try to align declarations and assignments in columns, when it proves
    logical. For example (taken from ttraster.c)

   struct _TProfile
  {                                                                     
    Int        flow;        /* Profile orientation : Asc/Descending     */
    Int        height;      /* profile's height in scanlines            */
    Int        start;       /* profile's start scanline                 */
    ULong      offset;      /* offset of profile's data in render pool  */
    PProfile   link;        /* link to next profile                     */
    Int        index;       /* index of profile's entry in trace table  */
    Int        count_lines; /* count of lines having to be drawn        */
    Int        start_line;  /* lines to be rendered before this profile */
    PTraceRec  trace;       /* pointer to profile's current trace table */
  };
 
    instead of

   struct _TProfile {
    Int flow;           /* Profile orientation : Asc/Descending     */
    Int height;         /* profile's height in scanlines            */
    Int start;          /* profile's start scanline                 */
    ULong offset;       /* offset of profile's data in render pool  */
    PProfile link;      /* link to next profile                     */
    Int index;          /* index of profile's entry in trace table  */
    Int count_lines;    /* count of lines having to be drawn        */
    Int start_line;     /* lines to be rendered before this profile */
    PTraceRec  trace;   /* pointer to profile's current trace table */
  };

    That comes from the fact that you're more interested by the variable and
    its function than by its type.

    Or
      x   = i+1;
      y  += j;
      min = 100;

    instead of

      x=i+1;
      y+=j;
      min=100;

    And don't hesitate to separate blocks of declarations with newlines
    to "distinguish" logical sections.

  - By the way, avoid hungarian notation like the plague if you want to be
    able to change you structures easily. This is only useful when working
    with a fixed API, wich is not our case. Moreover, it locks you in the
    API when your job is to concentrate on the program's tasks, not its
    interface.

  - I like underscores in names better, like Load_File instead of LoadFile.
    I admit that there is little justification for this except a better
    readability ( one which is completely against most of the coding
    standards I've seen, except in Ada95 ).

    Any function name begins with a capital letter, with each underscore
    followed by a capital letter. For variables, I have been less consistant:
    either all letters are lower-cased, with underscores, or the variable
    name does not begin with a capital letter but holds some, like in
    "unitsPerEM" ( this rules is mostly employed in the specs ). Pick one
    which pleases you.

    I think that there may be some important variables beginning with a
    capital letter. Those should be corrected..

  - Limit your lines to 78 characters, that's important to print the code
    and keep it "clean".

  - We may use a tool to reformat the code, but *NOT* until the final release,
    *PLEASE* !. I want something with the current identation at least for me,
    because it will be much easier for me to debug than a K&R ( irrrk !! )
    syntax. The Linux Kernel gives me headaches !! ( Well, more exactly,
    I feel that the K&R writing if very far from the way I mentally organize
    a program, and I spend too much time "translating" ). I love those spaces,
    newlines and columns :)

- as a convention, all types, except the most simple ones ( like scalars )
  have their name beginning with a capital 'T', like in 'TFoo'. You'll note
  that the first letter of 'foo' is also a capital.

  The corresponding pointer type, i.e. (TFoo*), is named PFoo.

  This may not seem of great use at first sight, but experience shows
  that it cuts a lot of headeaches, as you immediately recognize types
  and pointers when you see them.

  This of course is for the engine's internal types. The 'external' types
  found in 'freetype.h' all begin with 'TT_'.


- Pascal has a very useful 'with' clause that has no equivalent in C.
  One can usually get the same effect by defining a temporary variable
  like replacing a :

    with instance^.pts do
    begin
      cur_x^[p] = 0;
      cur_y^[p] = 0;
    end;

  by

    apoints = &instance->pts;

    apoints->cur_x[p] = 0;
    apoints->cur_y[p] = 0;

  Here, the convention is to append an 'a' to an explicit name.
  I call this kind of variable an 'alias', hence the 'a'.

  Note that this is not hungarian notation, we notice the function, not
  the type of the variable !

  There are examples of this in the interpreter within the 'Run'
  function, with 'aargs', 'atop', etc ..

  I have seen in the interpreter some aliases generated with 'type'
  names like in :

    TDefRecord  tdr;

    tdr = instance->FDefs[...];

    tdr->opcode = .....;

  I would rather recommend giving them a more explicit name,
  like :

    afdef      or
    afuncDef   or
    afunction  etc..
    

- note that I also chose an 'a' to denote parameters in functions.
  Though this is something that I rarely do in Pascal, it is useful in C
  where you have no control on the scope of variables, i.e. Pascal
  allows you to write things like :

    program Foo;

    var
      index : integer;
    
      procedure Bar( index : integer );
      begin
        Foo.index := index;
      end;


  while you can't in C, so you get :

      void Bar( int  aIndex )
      {
        index = aIndex;
      }

  note that usually, the parameter name's first letter is capitalized, to
  distinguish them from aliases.



