Standard library 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!