Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 273 lines (202 sloc) 6.26 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
05330ba @tibbe Remove the ToC as numbered headings don't work well in Markdown
authored
9 Formatting
10 ----------
8f343b5 @tibbe Added a first version of the style guide.
authored
11
12 ### Line Length
13
14 Maximum line length is *80 characters*.
15
16 ### Indentation
17
18 Tabs are illegal. Use spaces for indenting. Indent your code blocks
19 with *4 spaces*. Indent the `where` keyword two spaces to set it
20 apart from the rest of the code and indent the definitions in a
21 `where` clause 2 spaces. Some examples:
22
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
23 ```haskell
24 sayHello :: IO ()
25 sayHello = do
26 name <- getLine
27 putStrLn $ greeting name
28 where
29 greeting name = "Hello, " ++ name ++ "!"
30
31 filter :: (a -> Bool) -> [a] -> [a]
32 filter _ [] = []
33 filter p (x:xs)
34 | p x = x : filter p xs
35 | otherwise = filter p xs
36 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
37
38 ### Blank Lines
39
40 One blank line between top-level definitions. No blank lines between
41 type signatures and function definitions. Add one blank line between
42 functions in a type class instance declaration if the functions bodies
43 are large. Use your judgement.
44
45 ### Whitespace
46
47 Surround binary operators with a single space on either side. Use
19caa1d @jaspervdj Consistent spelling of "judgement".
jaspervdj authored
48 your better judgement for the insertion of spaces around arithmetic
8f343b5 @tibbe Added a first version of the style guide.
authored
49 operators but always be consistent about whitespace on either side of
50 a binary operator. Don't insert a space after a lambda.
51
52 ### Data Declarations
53
54 Align the constructors in a data type definition. Example:
55
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
56 ```haskell
57 data Tree a = Branch a (Tree a) (Tree a)
58 | Leaf
59 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
60
a5e6086 @tibbe Formatting of data types with long type names
authored
61 For long type names the following formatting is also acceptable:
62
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
63 ```haskell
64 data HttpException
65 = InvalidStatusCode Int
66 | MissingContentHeader
67 ```
a5e6086 @tibbe Formatting of data types with long type names
authored
68
8f343b5 @tibbe Added a first version of the style guide.
authored
69 Format records as follows:
70
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
71 ```haskell
72 data Person = Person
73 { firstName :: String -- ^ First name
74 , lastName :: String -- ^ Last name
75 , age :: Int -- ^ Age
76 } deriving (Eq, Show)
77 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
78
c261011 @jaspervdj Added section about list declarations.
jaspervdj authored
79 ### List Declarations
80
81 Align the elements in the list. Example:
82
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
83 ```haskell
84 exceptions =
85 [ InvalidStatusCode
86 , MissingContentHeader
87 , InternalServerError
88 ]
89 ```
c261011 @jaspervdj Added section about list declarations.
jaspervdj authored
90
91 Optionally, you can skip the first newline. Use your judgement.
92
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
93 ```haskell
94 directions = [ North
95 , East
96 , South
97 , West
98 ]
99 ```
c261011 @jaspervdj Added section about list declarations.
jaspervdj authored
100
8f343b5 @tibbe Added a first version of the style guide.
authored
101 ### Pragmas
102
103 Put pragmas immediately following the function they apply to.
104 Example:
105
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
106 ```haskell
107 id :: a -> a
108 id x = x
109 {-# INLINE id #-}
110 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
111
112 In the case of data type definitions you must put the pragma before
113 the type it applies to. Example:
114
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
115 ```haskell
116 data Array e = Array
117 {-# UNPACK #-} !Int
118 !ByteArray
119 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
120
121 ### Hanging Lambdas
122
123 You may or may not indent the code following a "hanging" lambda. Use
124 your judgement. Some examples:
125
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
126 ```haskell
127 bar :: IO ()
128 bar = forM_ [1, 2, 3] $ \n -> do
129 putStrLn "Here comes a number!"
130 print n
8f343b5 @tibbe Added a first version of the style guide.
authored
131
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
132 foo :: IO ()
133 foo = alloca 10 $ \a ->
134 alloca 20 $ \b ->
135 cFunction a b
136 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
137
d5bc02d @tibbe Export list formatting
authored
138 ### Export Lists
139
140 Format export lists as follows:
141
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
142 ```haskell
143 module Data.Set
144 (
145 -- * The @Set@ type
146 Set
147 , empty
148 , singleton
d5bc02d @tibbe Export list formatting
authored
149
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
150 -- * Querying
151 , member
152 ) where
153 ```
d5bc02d @tibbe Export list formatting
authored
154
05330ba @tibbe Remove the ToC as numbered headings don't work well in Markdown
authored
155 Imports
156 -------
8f343b5 @tibbe Added a first version of the style guide.
authored
157
158 Imports should be grouped in the following order:
159
160 1. standard library imports
161 2. related third party imports
162 3. local application/library specific imports
163
164 Put a blank line between each group of imports. The imports in each
165 group should be sorted alphabetically, by module name.
166
167 Always use explicit import lists or `qualified` imports for standard
168 and third party libraries. This makes the code more robust against
169 changes in these libraries. Exception: The Prelude.
170
05330ba @tibbe Remove the ToC as numbered headings don't work well in Markdown
authored
171 Comments
172 --------
8f343b5 @tibbe Added a first version of the style guide.
authored
173
174 ### Punctuation
175
176 Write proper sentences; start with a capital letter and use proper
177 punctuation.
178
179 ### Top-Level Definitions
180
181 Comment every top level function (particularly exported functions),
182 and provide a type signature; use Haddock syntax in the comments.
74d065c @tibbe Document how to format long Haddock comments on fields
authored
183 Comment every exported data type. Function example:
8f343b5 @tibbe Added a first version of the style guide.
authored
184
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
185 ```haskell
186 -- | Send a message on a socket. The socket must be in a connected
187 -- state. Returns the number of bytes sent. Applications are
188 -- responsible for ensuring that all data has been sent.
189 send :: Socket -- ^ Connected socket
190 -> ByteString -- ^ Data to send
191 -> IO Int -- ^ Bytes sent
74d065c @tibbe Document how to format long Haddock comments on fields
authored
192 ```
193
194 For functions the documentation should give enough information to
195 apply the function without looking at the function's definition.
196
197 Record example:
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
198
74d065c @tibbe Document how to format long Haddock comments on fields
authored
199 ```haskell
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
200 -- | Bla bla bla.
201 data Person = Person
202 { age :: Int -- ^ Age
203 , name :: String -- ^ First name
204 }
205 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
206
74d065c @tibbe Document how to format long Haddock comments on fields
authored
207 For fields that require longer comments format them like so:
208
209 ```haskell
210 data Record = Record
211 { -- | This is a very very very long comment that is split over
212 -- multiple lines.
213 field1 :: Text
214
215 -- | This is a second very very very long comment that is split
216 -- over multiple lines.
217 , field2 :: Int
218 }
219 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
220
221 ### End-of-Line Comments
222
223 Separate end-of-line comments from the code using 2 spaces. Align
224 comments for data type definitions. Some examples:
225
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
226 ```haskell
227 data Parser = Parser
228 Int -- Current position
229 ByteString -- Remaining input
8f343b5 @tibbe Added a first version of the style guide.
authored
230
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
231 foo :: Int -> Int
232 foo n = salt * 32 + 9
233 where
234 salt = 453645243 -- Magic hash salt.
235 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
236
e79773f Added comment regarding use of in-line links
Johan Tibell authored
237 ### Links
238
239 Use in-line links economically. You are encouraged to add links for
240 API names. It is not necessary to add links for all API names in a
241 Haddock comment. We therefore recommend adding a link to an API name
242 if:
243
244 * The user might actually want to click on it for more information (in
4741eef @dag Add back list indentation
dag authored
245 your judgment), and
e79773f Added comment regarding use of in-line links
Johan Tibell authored
246
247 * Only for the first occurrence of each API name in the comment (don't
4741eef @dag Add back list indentation
dag authored
248 bother repeating a link)
e79773f Added comment regarding use of in-line links
Johan Tibell authored
249
05330ba @tibbe Remove the ToC as numbered headings don't work well in Markdown
authored
250 Naming
251 ------
8f343b5 @tibbe Added a first version of the style guide.
authored
252
253 Use mixed-case when naming functions and camel-case when naming data
73d1990 @tibbe Remove expections in function naming
authored
254 types.
8f343b5 @tibbe Added a first version of the style guide.
authored
255
fc42348 @tibbe Fixed some typos.
authored
256 For readability reasons, don't capitalize all letters when using an
257 abbreviation. For example, write `HttpServer` instead of
258 `HTTPServer`. Exception: Two letter abbreviations, e.g. `IO`.
8f343b5 @tibbe Added a first version of the style guide.
authored
259
3315d30 @tibbe Add a note about module naming
authored
260 ### Modules
261
262 Use singular when naming modules e.g. use `Data.Map` and
263 `Data.ByteString.Internal` instead of `Data.Maps` and
264 `Data.ByteString.Internals`.
265
05330ba @tibbe Remove the ToC as numbered headings don't work well in Markdown
authored
266 Misc
267 ----
8f343b5 @tibbe Added a first version of the style guide.
authored
268
269 ### Warnings ###
270
271 Code should be compilable with `-Wall -Werror`. There should be no
272 warnings.
Something went wrong with that request. Please try again.