/* 
 * Coding standards. Revised 9/13/1999
 *
 *  Copyright (c) 1998 Ryan C. Gordon and Gregory S. Read.
 *   Written by Ryan C. Gordon.
 */

- Every file will start with a comment containing an explanation of what
   the module is for, and a copyright, in the format at the top of this
   file. The revision date is not necessary, but doesn't hurt. More detail
   than the above is definitely welcome. !!! GPL?

- End every file with a "/* end of MyFile.c ... */", so we know that the
   end of the file hasn't been thrashed in file transfer.

- C code should not use "//" comments. Not all "ANSI" compilers in existance
   necessarily like them. C++ code can use them freely.

- Comment excessively. The heading of each function should explain what the
   function does, each parameter, and the return value. If there are possible
   BASIC runtime errors to be thrown, note them as well.

- Don't overcomment. This isn't assembler; some lines of code will just
   speak for themselves.

- If there's a piece of problem code, something to come back to, or a known
   bug that is identified but needs to be fixed, label the code with "!!!"
   so we can find it later, and know what it is.

   example:

   int foo(char bar)
   {
       /* !!! This needs a complete rewrite to handle widgets. */
   } /* foo */


   Standardizing this saves us trouble when we just need to do a text search
   to find weak points in the code.

- Alternately, #warning directives are acceptable, and more noticeable.

- No more than 80 characters to a line. Period.

- Never use TAB characters. Always spaces. Make sure your editor autoconverts.

- Why not? Let's call the indent size FOUR spaces, eh?

- This annoys me:

    void myFunc(Foo bar) {
        blahblahblah();
    }

  Do this:

    void myFunc(Foo bar)
    {
        blahBlahBlah();
    }


- It couldn't hurt, especially on large, complex functions, to comment what
   the end bracket goes to (this was the one saving grace of BASIC, there
   weren't ambiguous end brackets, there were END IF, END FUNCTION, etc...)

   if (foo == bar)
   {
       _do(something);
   } /* if */ <--- That thing. Do that. It helps, I promise.


- Capitalizations. I like the Java standards on this one: variables' and
   functions' first letters are uppercase, except the first word:

      printToScreen(anotherCoolVariable);

  Class names, structures, etc...are capitalized for every word.

      MyCoolClassName instanceOfCoolClass = new MyCoolClassName();

  Filenames (which in Java must be identical to the contained class' name)
   will be capitalized like class names. Filenames should fit the module,
   and API modules should end with "Functions". (i.e. -- an API module might
   be called MathFunctions.c or FileIOFunctions.c ...) Internal BASIClib
   modules (that is, modules that aren't meant to fill in standard BASIC APIs)
   do not end in "Functions": BasicString.c, MemoryManager.c ...

  Constants and macros are completely capitalized, and since they don't have
   the luxury of lowercase letters, you can signify word separations with an
   underscore character.

  #define CRACK_PIPE 10
  #define BUTTS(x) ((x > CRACK_PIPE) ? x : CRACK_PIPE)

  Macros that are meant to look like functions (like __doGosub) may be
   capitalized like function names.

- In C/C++, since we can't necessarily use '$' in identifiers, we'll replace
   it with "_DC_". (underscore-D-C-underscore. DC is for "dollar char.") This
   will be needed for things like the basic library functions "chr$()" and
   converting valid user variable names in BASIC to C to pass to gcc.
   Other problem characters are "_PC_"  ('%'...percent char), "_EC_"
   ('!'...exclamation char), "_AC_" ('&'...ampersand char), etc...

- Please refer to name_mangling.txt for a detailed explanation of function
    naming conventions.

- General, personalized coding practices should be duplicated when modifying
   others' code. Keep your own style for your own file. I don't care if the
   tab size in someone else's file pisses you off. Make it easy for the
   original author to comprehend what you've done to his work.

- Keep it simple, stupid.


/* end of coding.txt ... */

