Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 190 lines (135 sloc) 5.074 kb
8f343b5 @tibbe Added a first version of the style guide.
authored
1 Haskell Style Guide
2 ===================
3
4 This is a short document describing the preferred coding style for
5 this project. I've tried to cover the major areas of formatting and
6 naming. When something isn't covered by this guide you should stay
7 consistent with the code in the other modules.
8
9 Table of Contents
10 -----------------
11
12 1. Formatting
13 2. Imports
14 3. Comments
15 4. Naming
16 5. Misc
17
18 1. Formatting
19 -------------
20
21 ### Line Length
22
23 Maximum line length is *80 characters*.
24
25 ### Indentation
26
27 Tabs are illegal. Use spaces for indenting. Indent your code blocks
28 with *4 spaces*. Indent the `where` keyword two spaces to set it
29 apart from the rest of the code and indent the definitions in a
30 `where` clause 2 spaces. Some examples:
31
32 sayHello :: IO ()
33 sayHello = do
34 name <- getLine
35 putStrLn $ greeting name
36 where
37 greeting name = "Hello, " ++ name ++ "!"
38
39 filter :: (a -> Bool) -> [a] -> [a]
40 filter _ [] = []
41 filter p (x:xs)
42 | p x = x : filter p xs
43 | otherwise = filter p xs
44
45 ### Blank Lines
46
47 One blank line between top-level definitions. No blank lines between
48 type signatures and function definitions. Add one blank line between
49 functions in a type class instance declaration if the functions bodies
50 are large. Use your judgement.
51
52 ### Whitespace
53
54 Surround binary operators with a single space on either side. Use
55 your better judgment for the insertion of spaces around arithmetic
56 operators but always be consistent about whitespace on either side of
57 a binary operator. Don't insert a space after a lambda.
58
59 ### Data Declarations
60
61 Align the constructors in a data type definition. Example:
62
63 data Tree a = Branch a (Tree a) (Tree a)
64 | Leaf
65
66 Format records as follows:
67
68 data Person = Person
69 { firstName :: String -- ^ First name
70 , lastName :: String -- ^ Last name
71 , age :: Int -- ^ Age
72 } deriving (Eq, Show)
73
74 ### Pragmas
75
76 Put pragmas immediately following the function they apply to.
77 Example:
78
79 id :: a -> a
80 id x = x
81 {-# INLINE id #-}
82
83 In the case of data type definitions you must put the pragma before
84 the type it applies to. Example:
85
86 data Array e = Array
87 {-# UNPACK #-} !Int
88 !ByteArray
89
90 ### Hanging Lambdas
91
92 You may or may not indent the code following a "hanging" lambda. Use
93 your judgement. Some examples:
94
95 bar :: IO ()
96 bar = forM_ [1, 2, 3] $ \n ->
97 putStrLn "Here comes a number!"
98 print n
99
100 foo :: IO ()
101 foo = alloca 10 $ \a ->
102 alloca 20 $ \b ->
103 cFunction a b
104
105 2. Imports
106 ----------
107
108 Imports should be grouped in the following order:
109
110 1. standard library imports
111 2. related third party imports
112 3. local application/library specific imports
113
114 Put a blank line between each group of imports. The imports in each
115 group should be sorted alphabetically, by module name.
116
117 Always use explicit import lists or `qualified` imports for standard
118 and third party libraries. This makes the code more robust against
119 changes in these libraries. Exception: The Prelude.
120
121 3. Comments
122 -----------
123
124 ### Line Length
125
126 Maximum line length is *70 characters*. This increases readability as
127 the eye has to travel back to the start of the next line.
128
129 ### Punctuation
130
131 Write proper sentences; start with a capital letter and use proper
132 punctuation.
133
134 ### Top-Level Definitions
135
136 Comment every top level function (particularly exported functions),
137 and provide a type signature; use Haddock syntax in the comments.
138 Comment every exported data type. Some examples:
139
140 -- | Send a message on a socket. The socket must be in a connected
141 -- state. Returns the number of bytes sent. Applications are
142 -- responsible for ensuring that all data has been sent.
143 send :: Socket -- ^ Connected socket
144 -> ByteString -- ^ Data to send
fc42348 @tibbe Fixed some typos.
authored
145 -> IO Int -- ^ Bytes sent
8f343b5 @tibbe Added a first version of the style guide.
authored
146
147 -- | Bla bla bla.
148 data Person = Person
149 { age :: Int -- ^ Age
150 , name :: String -- ^ First name
151 }
152
153 For functions the documentation should give enough information to
154 apply the function without looking at the functions definition.
155
156 ### End-of-Line Comments
157
158 Separate end-of-line comments from the code using 2 spaces. Align
159 comments for data type definitions. Some examples:
160
161 data Parser = Parser
162 Int -- Current position
163 ByteString -- Remaining input
164
165 foo :: Int -> Int
166 foo n = salt * 32 + 9
167 where
168 salt = 453645243 -- Magic hash salt.
169
170 4. Naming
171 ---------
172
173 Use mixed-case when naming functions and camel-case when naming data
174 types. There are a few exceptions that are widely used.
175
176 1. QuickCheck properties use a `prop_` prefix.
177 2. FFI wrapper use a `c_` prefix.
178
fc42348 @tibbe Fixed some typos.
authored
179 For readability reasons, don't capitalize all letters when using an
180 abbreviation. For example, write `HttpServer` instead of
181 `HTTPServer`. Exception: Two letter abbreviations, e.g. `IO`.
8f343b5 @tibbe Added a first version of the style guide.
authored
182
183 5. Misc
184 -------
185
186 ### Warnings ###
187
188 Code should be compilable with `-Wall -Werror`. There should be no
189 warnings.
Something went wrong with that request. Please try again.