Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 255 lines (188 sloc) 5.879 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.
183 Comment every exported data type. Some examples:
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
192
193 -- | Bla bla bla.
194 data Person = Person
195 { age :: Int -- ^ Age
196 , name :: String -- ^ First name
197 }
198 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
199
200 For functions the documentation should give enough information to
48d30d3 corrected possessive with apostrophe
Chris Done authored
201 apply the function without looking at the function's definition.
8f343b5 @tibbe Added a first version of the style guide.
authored
202
203 ### End-of-Line Comments
204
205 Separate end-of-line comments from the code using 2 spaces. Align
206 comments for data type definitions. Some examples:
207
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
208 ```haskell
209 data Parser = Parser
210 Int -- Current position
211 ByteString -- Remaining input
8f343b5 @tibbe Added a first version of the style guide.
authored
212
9cb5dae @dag Syntax highlighting via GitHub Flavored Markdown
dag authored
213 foo :: Int -> Int
214 foo n = salt * 32 + 9
215 where
216 salt = 453645243 -- Magic hash salt.
217 ```
8f343b5 @tibbe Added a first version of the style guide.
authored
218
e79773f Added comment regarding use of in-line links
Johan Tibell authored
219 ### Links
220
221 Use in-line links economically. You are encouraged to add links for
222 API names. It is not necessary to add links for all API names in a
223 Haddock comment. We therefore recommend adding a link to an API name
224 if:
225
226 * The user might actually want to click on it for more information (in
4741eef @dag Add back list indentation
dag authored
227 your judgment), and
e79773f Added comment regarding use of in-line links
Johan Tibell authored
228
229 * Only for the first occurrence of each API name in the comment (don't
4741eef @dag Add back list indentation
dag authored
230 bother repeating a link)
e79773f Added comment regarding use of in-line links
Johan Tibell authored
231
05330ba @tibbe Remove the ToC as numbered headings don't work well in Markdown
authored
232 Naming
233 ------
8f343b5 @tibbe Added a first version of the style guide.
authored
234
235 Use mixed-case when naming functions and camel-case when naming data
73d1990 @tibbe Remove expections in function naming
authored
236 types.
8f343b5 @tibbe Added a first version of the style guide.
authored
237
fc42348 @tibbe Fixed some typos.
authored
238 For readability reasons, don't capitalize all letters when using an
239 abbreviation. For example, write `HttpServer` instead of
240 `HTTPServer`. Exception: Two letter abbreviations, e.g. `IO`.
8f343b5 @tibbe Added a first version of the style guide.
authored
241
3315d30 @tibbe Add a note about module naming
authored
242 ### Modules
243
244 Use singular when naming modules e.g. use `Data.Map` and
245 `Data.ByteString.Internal` instead of `Data.Maps` and
246 `Data.ByteString.Internals`.
247
05330ba @tibbe Remove the ToC as numbered headings don't work well in Markdown
authored
248 Misc
249 ----
8f343b5 @tibbe Added a first version of the style guide.
authored
250
251 ### Warnings ###
252
253 Code should be compilable with `-Wall -Werror`. There should be no
254 warnings.
Something went wrong with that request. Please try again.