STANDARDS.md 2.79 KB
Newer Older
1 2
The following guidelines should be adhered to when developing libraries for the
Clean Platform library collection.
3

Mart Lubbers's avatar
Mart Lubbers committed
4 5
## Type names 

6 7
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
8 9
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).
10

Mart Lubbers's avatar
Mart Lubbers committed
11 12
## Function names 

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

Mart Lubbers's avatar
Mart Lubbers committed
17 18
## Module names 

19 20 21 22
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
Mart Lubbers's avatar
Mart Lubbers committed
23 24
module with an underscore character or place it in a separate Internal
submodule.
25

Mart Lubbers's avatar
Mart Lubbers committed
26 27
## Argument order 

28 29 30
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:
31

Mart Lubbers's avatar
Mart Lubbers committed
32
- State representing arguments such as the common `*World` type argument,
Mart Lubbers's avatar
Mart Lubbers committed
33 34 35
  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.
36

Mart Lubbers's avatar
Mart Lubbers committed
37
## Comments 
38 39 40
A concise description of the purpose of a function and the meaning of its input
and output parameters should be present in the .dcl file for all exported
functions. Comments are specified as follows:
41

Mart Lubbers's avatar
Mart Lubbers committed
42
```
43
/**
44
 * This function is the identity.
45 46 47
 */
id :: a -> a
id x = x
Mart Lubbers's avatar
Mart Lubbers committed
48
```
49

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

Mart Lubbers's avatar
Mart Lubbers committed
54 55
## Layout 

Mart Lubbers's avatar
Mart Lubbers committed
56 57
Tabs should be used for indentation. Spaces for alignment.
`where` clauses should not be indented.
58

Mart Lubbers's avatar
Mart Lubbers committed
59 60
## Exporting functions and types =

61 62 63 64 65
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
66 67 68 69 70 71 72
- Explicitly import the types and classes you need for specifying the type
  signatures by using the "from ... import ..." notation.

- Only ever import an entire module with the "import ..." notation if you
  really truly want to re-export the entire module.

Implementation modules may import anything they like.
73

Mart Lubbers's avatar
Mart Lubbers committed
74
## Implementing class instances and generic derives 
75