STANDARDS.md 3.63 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

6 7 8 9 10 11 12 13 14
## What is the purpose of Clean Platform

Clean Platform was created to have a central place where commonly used
functionality was stored so that people didn't have to look for it. All the
functionality should be available on all platforms. This means that
functionality only working on Windows has no place here. It is allowed to
simulate functionality across systems. Examples of this is the System.Process
module that offers the same API across platforms.

Mart Lubbers's avatar
Mart Lubbers committed
15 16
## Type names 

17 18
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
19 20
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).
21

Mart Lubbers's avatar
Mart Lubbers committed
22 23
## Function names 

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

Mart Lubbers's avatar
Mart Lubbers committed
28 29
## Module names 

30 31 32 33
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
34
module with an underscore character (`_`) or place it in a separate `Internal`
Mart Lubbers's avatar
Mart Lubbers committed
35
submodule.
36

Mart Lubbers's avatar
Mart Lubbers committed
37 38
## Argument order 

39 40 41
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:
42

Mart Lubbers's avatar
Mart Lubbers committed
43
- State representing arguments such as the common `*World` type argument,
Mart Lubbers's avatar
Mart Lubbers committed
44 45 46
  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.
47

Mart Lubbers's avatar
Mart Lubbers committed
48
## Comments 
49

50 51 52 53 54 55
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
56
/**
57
 * This function is the identity.
58 59
 * @param Some value
 * @result The same value
60 61 62
 */
id :: a -> a
id x = x
Mart Lubbers's avatar
Mart Lubbers committed
63
```
64

Mart Lubbers's avatar
Mart Lubbers committed
65
Several JavaDoc like parameters are supported such as `@param`, `@result`,
66 67
`@type`, `@var` and `@representation`. More info about this can be found
[here](https://github.com/clean-cloogle/Cloogle#clean-documentation).
68 69 70
We use `@complexity` for the complexity order. Some other special fields are
used, like `@gin-icon`, but one should be reluctant with inventing new field
names. If there is a general use case, adding it can be discussed.
71

Mart Lubbers's avatar
Mart Lubbers committed
72 73
## Layout 

74 75
- Tabs should be used for indentation. Spaces for alignment.
- The `where` keyword should be at the same level as the parent code block.
76

77
## Exporting functions and types
Mart Lubbers's avatar
Mart Lubbers committed
78

79 80 81 82 83
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
84
- Explicitly import the types and classes you need for specifying the type
85
  signatures by using the `from ... import ...` notation.
Mart Lubbers's avatar
Mart Lubbers committed
86

87
- Only ever import an entire module with the `import ...` notation if you
Mart Lubbers's avatar
Mart Lubbers committed
88 89 90
  really truly want to re-export the entire module.

Implementation modules may import anything they like.
91

Mart Lubbers's avatar
Mart Lubbers committed
92
## Implementing class instances and generic derives 
93