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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
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@compsoc.dur.ac.uk).
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. Always
name exceptions (i.e. define a constant) so that the library user
can check. Additionally, make sure each Exception has a unique error
number. The following are suggested ranges for each module. Document
additional ranges here as exceptions are added to new modules.
--- reserved for RTS ---
RTS: 0-9
--- base modules ---
Prelude: 10-19
Array: 20-29
Builtins: 30-39
--- non Web(app|prog)-specific modules ---
Binary: 100-109
Crypto: 110-119
HTTP: 120-129
IO: 130-139
Lazy: 140-149
Mail: 150-159
Net: 160-169
Parse: 170-189
Time: 190-199
TLS: 200-209
Strings: 210-219
--- Web(app|prog) modules ---
ElementTreeData 500-509
HTMLDocument 510-519
Webapp 520-529
Webprog 530-539
XMLentities 540-549
ElementTree 550-559
--- Platform dependent libraries ---
Posix 800-810
Syslog 810-820
If the exception needs to represent some sort of error code, use
negative integers (see Posix::NonZeroExit for an example). In this case
keep the error string constant so it can be checked in the catch block.
* 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!
|
