STANDARDS.md 2.97 KB
Newer Older
1 2
# Standards

3 4
The following guidelines should be adhered to when developing libraries for the
Clean Platform library collection.
5

Mart Lubbers's avatar
Mart Lubbers committed
6 7
## Type names 

8 9
The names of types should be clear and informative, and should always start
with a capital.  If the name of a type consists of multiple words, each new
10 11
word should start with a capital.  Whenever the name is an abbreviation the
abbreviation should be written using only capitals (e.g. GUI,SQL,HTTP).
12

Mart Lubbers's avatar
Mart Lubbers committed
13 14
## Function names 

Mart Lubbers's avatar
Mart Lubbers committed
15
Function names should be written in lowerCamelCase. By starting types and
16
constructors with a capital and functions without one, the difference between
Mart Lubbers's avatar
Mart Lubbers committed
17
a constructor and a function is immediately clear for the reader of a program.
18

Mart Lubbers's avatar
Mart Lubbers committed
19 20
## Module names 

21 22 23 24
For modules, the same guidelines apply as for naming types. Names should be
informative and preferably short. When a library module is not meant for direct
imports by end users, but should only used by experts in modules that for
example provide a more friendly interface, you should prefix the name of that
25
module with an underscore character (`_`) or place it in a separate `Internal`
Mart Lubbers's avatar
Mart Lubbers committed
26
submodule.
27

Mart Lubbers's avatar
Mart Lubbers committed
28 29
## Argument order 

30 31 32
While there are no hard demands on the order in which you specify the arguments
of functions, there are two rules which make your functions easier to use and
somewhat more clear:
33

Mart Lubbers's avatar
Mart Lubbers committed
34
- State representing arguments such as the common `*World` type argument,
Mart Lubbers's avatar
Mart Lubbers committed
35 36 37
  should be at the end of the argument list.
- Arguments which are used as "options" in some way should be at the beginning
  of the arguments. This makes it easy to pass in options by currying.
38

Mart Lubbers's avatar
Mart Lubbers committed
39
## Comments 
40

41 42 43 44 45 46
A concise description of the purpose of a function and the meaning of its
arguments and result should be present in the .dcl file for all exported
functions. The documentation should not be included in the .icl file for
maintainability. Comments are specified as follows:

```clean
47
/**
48
 * This function is the identity.
49 50
 * @param Some value
 * @result The same value
51 52 53
 */
id :: a -> a
id x = x
Mart Lubbers's avatar
Mart Lubbers committed
54
```
55

Mart Lubbers's avatar
Mart Lubbers committed
56
Several JavaDoc like parameters are supported such as `@param`, `@result`,
57 58
`@type`, `@var` and `@representation`. More info about this can be found
[here](https://github.com/clean-cloogle/Cloogle#clean-documentation).
59

Mart Lubbers's avatar
Mart Lubbers committed
60 61
## Layout 

62 63
- Tabs should be used for indentation. Spaces for alignment.
- The `where` keyword should be at the same level as the parent code block.
64

65
## Exporting functions and types
Mart Lubbers's avatar
Mart Lubbers committed
66

67 68 69 70 71
Definition modules (.dcl) must be very specific about the modules they import
because everything imported in a definition module is exported as well,
increasing the chance of name collisions. To minimize the chance for
collisions, adhere to the following conventions:

Mart Lubbers's avatar
Mart Lubbers committed
72
- Explicitly import the types and classes you need for specifying the type
73
  signatures by using the `from ... import ...` notation.
Mart Lubbers's avatar
Mart Lubbers committed
74

75
- Only ever import an entire module with the `import ...` notation if you
Mart Lubbers's avatar
Mart Lubbers committed
76 77 78
  really truly want to re-export the entire module.

Implementation modules may import anything they like.
79

Mart Lubbers's avatar
Mart Lubbers committed
80
## Implementing class instances and generic derives 
81