Conventions

All standard library functions are required to conform to the standard library conventions. Please let us know if you think any fail to match this. The current version can always be found in stdlib/CONVENTIONS in the Kaya source code.

Proposed changes to the interface conventions are discussed on the kaya-devel mailing list.

Library conventions
-------------------
ECB, 17/03/06

Exported standard library function names should conform to the
following conventions, for a consistent interface. These are vague and
informal in some cases, as it is quite hard to give hard and fast
guidelines for every function which hasn't been written yet - if in
doubt, ask the mailing list ([email protected]).

I've derived these from the way the library has been implemented up to
0.2.0pre. If you'd like to make any changes or additions, please ask
the mailing list first.

* Function names with more than one word should be written likeThis,
  rather than like_this, and *definitely* not likethis.
  i.e. first word has no capital, subsequent words are capitalised.
* Further to the above, keep function names as short as possible
  without abusing abbreviations. Keep typing to a minimum!
* Do not use the module name in a function name; that's what
  namespaces are for. e.g. use Dict::new rather than newDict.
* Constants (i.e. zero argument functions, including exceptions)
  should begin with a capital letter.
* Coercions should have the same name as the data type, but should begin
  with a lowercase letter as normal. In certain cases, this convention
  may be stretched slightly. (so string rather than toString, but xyType
  is probably better than xYType or xytype for coercions to XYType) - use
  common sense when deciding where the word boundaries are.
* verbNoun rather than nounVerb. (e.g. packString rather than stringPack)
* Overload names provided that the names are used in a consistent way.
  Use caution when overloading common function names when the function type
  is not unique.
* Use suffix 'At' for operations on a specific point in a data
  structure, (e.g. removeAt, addElementAt, etc).
* If two functions are inverses, try to make this clear in the name
  (e.g. shift and unshift).
* 'get' and 'set' prefixes are often just noise. Avoid, unless they
  are definitely a pair of functions.
* Direct calls to standard C library functions might as well have C
  names (e.g. srand, mkdir).

Data type names should conform to the following conventions

* Data types with more than one word should be written LikeThis,
  rather than Like_This.
* Where possible, a module written around one primary data structure
  (e.g. Dict or Binary) should have the same name as the data
  structure.

Function behaviour
------------------

* Usually, it is better to use default arguments when a function has
  default behaviour which can be altered (e.g. sort's comparison
  operator). In cases where this is awkward (e.g. argument ordering,
  or slightly complicated default behaviour), use the suffix 'With',
  e.g. zipWith.
* Throw an exception rather than returning a code on error. 
* Try to make it as clear as possible from the name whether a function
  modifies its argument in-place, or returns a new
  value. e.g. 'remove' should modify an array by removing elements,
  not return a copy of the array.
 
Further coding conventions, being invisible to the kaya programmer,
need not be strict. However, it would be good for each library module
to be self-consistent, so try to conform to the convention of the
module's original author.

Miscreants
----------

Functions we've identified which break the above conventions (last
updated 25/03/06):
- feel free to add some if you find them!