Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 226 lines (161 sloc) 5.686 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
a5e6086 @tibbe Formatting of data types with long type names
authored
66 For long type names the following formatting is also acceptable:
67
68 data HttpException
69 = InvalidStatusCode Int
70 | MissingContentHeader
71
8f343b5 @tibbe Added a first version of the style guide.
authored
72 Format records as follows:
73
74 data Person = Person
75 { firstName :: String -- ^ First name
76 , lastName :: String -- ^ Last name
77 , age :: Int -- ^ Age
78 } deriving (Eq, Show)
79
c261011 @jaspervdj Added section about list declarations.
jaspervdj authored
80 ### List Declarations
81
82 Align the elements in the list. Example:
83
84 exceptions =
85 [ InvalidStatusCode
86 , MissingContentHeader
87 , InternalServerError
88 ]
89
90 Optionally, you can skip the first newline. Use your judgement.
91
92 directions = [ North
93 , East
94 , South
95 , West
96 ]
97
8f343b5 @tibbe Added a first version of the style guide.
authored
98 ### Pragmas
99
100 Put pragmas immediately following the function they apply to.
101 Example:
102
103 id :: a -> a
104 id x = x
105 {-# INLINE id #-}
106
107 In the case of data type definitions you must put the pragma before
108 the type it applies to. Example:
109
110 data Array e = Array
111 {-# UNPACK #-} !Int
112 !ByteArray
113
114 ### Hanging Lambdas
115
116 You may or may not indent the code following a "hanging" lambda. Use
117 your judgement. Some examples:
118
119 bar :: IO ()
a8b9da2 @tibbe Added missing do after lambda. Closes #1
authored
120 bar = forM_ [1, 2, 3] $ \n -> do
8f343b5 @tibbe Added a first version of the style guide.
authored
121 putStrLn "Here comes a number!"
122 print n
123
124 foo :: IO ()
125 foo = alloca 10 $ \a ->
126 alloca 20 $ \b ->
127 cFunction a b
128
d5bc02d @tibbe Export list formatting
authored
129 ### Export Lists
130
131 Format export lists as follows:
132
133 module Data.Set
134 (
135 -- * The @Set@ type
136 Set
137 , empty
138 , singleton
139
140 -- * Querying
141 , member
142 ) where
143
8f343b5 @tibbe Added a first version of the style guide.
authored
144 2. Imports
145 ----------
146
147 Imports should be grouped in the following order:
148
149 1. standard library imports
150 2. related third party imports
151 3. local application/library specific imports
152
153 Put a blank line between each group of imports. The imports in each
154 group should be sorted alphabetically, by module name.
155
156 Always use explicit import lists or `qualified` imports for standard
157 and third party libraries. This makes the code more robust against
158 changes in these libraries. Exception: The Prelude.
159
160 3. Comments
161 -----------
162
163 ### Line Length
164
165 Maximum line length is *70 characters*. This increases readability as
166 the eye has to travel back to the start of the next line.
167
168 ### Punctuation
169
170 Write proper sentences; start with a capital letter and use proper
171 punctuation.
172
173 ### Top-Level Definitions
174
175 Comment every top level function (particularly exported functions),
176 and provide a type signature; use Haddock syntax in the comments.
177 Comment every exported data type. Some examples:
178
179 -- | Send a message on a socket. The socket must be in a connected
180 -- state. Returns the number of bytes sent. Applications are
181 -- responsible for ensuring that all data has been sent.
182 send :: Socket -- ^ Connected socket
183 -> ByteString -- ^ Data to send
fc42348 @tibbe Fixed some typos.
authored
184 -> IO Int -- ^ Bytes sent
8f343b5 @tibbe Added a first version of the style guide.
authored
185
186 -- | Bla bla bla.
187 data Person = Person
188 { age :: Int -- ^ Age
189 , name :: String -- ^ First name
190 }
191
192 For functions the documentation should give enough information to
48d30d3 corrected possessive with apostrophe
Chris Done authored
193 apply the function without looking at the function's definition.
8f343b5 @tibbe Added a first version of the style guide.
authored
194
195 ### End-of-Line Comments
196
197 Separate end-of-line comments from the code using 2 spaces. Align
198 comments for data type definitions. Some examples:
199
200 data Parser = Parser
201 Int -- Current position
202 ByteString -- Remaining input
203
204 foo :: Int -> Int
205 foo n = salt * 32 + 9
206 where
207 salt = 453645243 -- Magic hash salt.
208
209 4. Naming
210 ---------
211
212 Use mixed-case when naming functions and camel-case when naming data
73d1990 @tibbe Remove expections in function naming
authored
213 types.
8f343b5 @tibbe Added a first version of the style guide.
authored
214
fc42348 @tibbe Fixed some typos.
authored
215 For readability reasons, don't capitalize all letters when using an
216 abbreviation. For example, write `HttpServer` instead of
217 `HTTPServer`. Exception: Two letter abbreviations, e.g. `IO`.
8f343b5 @tibbe Added a first version of the style guide.
authored
218
219 5. Misc
220 -------
221
222 ### Warnings ###
223
224 Code should be compilable with `-Wall -Werror`. There should be no
225 warnings.
Something went wrong with that request. Please try again.