1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
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 (kaya-devel@lists.kayalang.org).
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.
* traverse functions in stdlib should not modify the original data
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!
|
