-- @(#)GUIDELINES-OTSO	5.1 --

--------------------------------------
GUIDELINES FOR PROGRAMMERS USING OTSO
--------------------------------------

---------------------------------------------------------------
1. OTSO Documents
---------------------------------------------------------------
- Read OTSO User's Guide

---------------------------------------------------------------
2. C++ Coding Guidelines
---------------------------------------------------------------
- Use din and dout instead of cin and cout.

- Always say whether a const is extern or static
	In C++, consts have internal linkage by default. Since
	this may change in the future (ANSI), or you want your
	programs to be portable, always specify static or extern
	before const.  You normally want your consts to be static.

- Always try to use const instead of #define.  Now that const is available,
  const should be used as much as possible (this helps the compiler catch
  errors and in optimization).

- Classes should have few, short, inlines.
	As a rule of thumb, if your inline is longer than 2 or 3 lines,
	don't inline it.

- Class inlines CAN NOT be accessed by SOME debuggers like gdb 
  (for g++).  It may be necessary to move the inlines out of the class
  definition and into the .cxx if you wish to debug them (this is 
  especially troublesome for constructors which are often inlined).

- Always put "wrappers" in your .hxx header files:
    #ifndef FILENAME_HXX
    #define FILENAME_HXX
      contents of header
    #endif
	This is important, since header files are multiply included
	in C++, it prevents multiple definitions of variables, etc.

- Always use wrappers (when possible) in including files.
    #ifndef FILENAME_HXX
    #include "filename.hxx"
    #endif
	This is important, to make the cpp (c pre processor) more 
	efficient in including files.  If you say simply 
	#include "filename.hxx", and filename.hxx has been included
	at least once already, then cpp must parse the header all
	the way to the #endif of the header's wrapper.  This can
	take significant time for large headers.
         
---------------------------------------------------------------
3. C++ Coding Style Guidelines
---------------------------------------------------------------
- Always prefix globals with ::, members with this->, static
  members with name::
	This makes your code easier for others to read and
	understand.

- Preferred OTSO ordering of a Class Definition:
    1. private data
    2. private member functions 
    3. protected data
    4. protected member functions 
    5. public data
    6. public member functions (operators, constructors, destructors last).
	This is obviously a matter of taste and one's personal religion,
	but anarchy is better than no structure at all :-).

- Always begin class names with a Capital letter.

- Compiler switches should be all Capital letters (e.g. DEBUGGING).

- Always use braces for multiple ifs, elses

- Use default parameters for procedure calls whenever possible.

- Try not to use static class members and global variables.
  If you have to use them, remember to think about possible
  distribution and concurrent program execution, and
  use static class members rather than global variables.

- Use references instead of pointers when possible.

- Avoid explicit pointer casts.

- use void to denote an empty argument list (e.g. f(void)).

---------------------------------------------------------------
4. Configuring OTSO
---------------------------------------------------------------
- OTSO can be configured by modifying the files:
	/otso/enviros/env*.h*
	/otso/enviros/makes/system.make


---------------------------------------------------------------
5. PORTABILITY
---------------------------------------------------------------
- sint16 ... are defined in /otso/enviros/envOS.h
	use sint16, sint8, sint32 ... instead of int
	use uint16, uint8, uint32 ... instead of unsigned int
  As a default suggestion, if you don't know what to use for int, use sint16
  (or uint16 instead of unsigned int).

- Comment any sections of code you write that you suspect are not portable
  with the comment /* !! NON_PORTABLE !! */, so they are easier for others
  to find.

- Use compiler directives such as #ifdef BSD to compile OS/compiler specific
  code.  see /otso/enviros/env*.h* for various configuration switches used in
  compiler directives.

---------------------------------------------------------------
6. Filename convention
---------------------------------------------------------------
Please use the suffixes .tmp .keep .save or .old to name your temporary files
and directories.  These are ignored in the make target 'make release'.
This helps keep the released versions of OTSO relatively clean of junk.


	----------------------------------------------
	Add more comments to this file as you see fit.  
	Many other directories also have README files.
	----------------------------------------------

