$Header: /san01/cvs/ashpool/csrc/doc/Attic/standards.txt,v 1.3 2004/03/31 19:59:51 aleigh Exp $

-= API & Code Terms =-

This is an attempt to create a small glossary of "approved" terms,
mostly for use when naming function calls and objects. There has been
some drift over the months and even within my own code I use confusing
or inconsistent nomenclature.

The following are "approved" terms which should be use exclusively;
for example "create" should not be used in lieu of "init". 

init: Create / Allocate a thing

free: Destroy / De-Allocate a thing

add: Exclusivly add a thing to storage thing.
Only add if the thing was not already in the storage
thing unless the storage thing does not enforce
uniqueness.

replace: Replace one thing with another. Do not
add the thing if it was not already there.

update: Add/Replace the value of a thing in
a container.

delete: Delete a thing and destroy it.

remove: Remove a thing but return it instead of
destroying it.

find: Lookup a thing, search for a thing, get a specific thing.

-= Source Code =-

4 space tabs. Do not use the tab character.

One-True Brace Style.

No implicit blocks:

  if (a==1) {
    return 1;
  }

instead of

  if(a==1) 
    return 1;  

No implicit conditionals:

  if(a==0) 

instead of

  if(!a);

-= Return Status =-

Functions may have one of several return profiles depending on
their individual function. 

Standard Boolean:
-1 Error
 0 success

Standard State:
-1 Error
 0 did nothing
 1 did something

Standard I/O:
-1 Error
 n bytes read/written

