Haskell Style Guide
Updated 824 Days AgoPublic

This style guide is based on https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md. Some modifications have been made to accommodate 2-space indentation. It is intended to be used with Chromabits projects.

Formatting

Line Length

The soft-limit for line length is 80 characters. This promotes well-structured code and allows developers to open two files side by side on small screens. While on some cases, such as URLs, long module names, or comments, an 80 character limit this might not be possible to fulfill, most code can be formatted within this limit. Generally, if the syntax allows a line to be split, one should attempt to do so until it fits the limit.

Splitting lines

Additionally, when splitting long lines, always put the operator/symbol at the beginning of the next line:

-- | A bit long:
longLine :: IO
longLine = putStrLn . cs . mconcat $ ["This is a long line apparently. ", "What do you think?"]

-- | Good:
betterLine :: IO
betterLine = putStrLn . cs . mconcat
  $ ["This is a long line apparently. ", "What do you think?"]

-- | Starting the definition on a new line might improve readability
-- in some cases (use your judgement).
altLine :: IO
altLine
  = putStrLn . cs . mconcat
  $ ["This is a long line apparently. ", "What do you think?"]
Exceptions:

There are some known exceptions to this rule. Generally, if putting the operator on the next line is not convenient and makes the code "uglier", then it's best to leave it in the previous line:

Aligned lists/tuples:

If there are two adjacent symbols and the second one is part of an aligned structure such as a list or tuple, the first symbol should go on the previous line. For example:

uglyLines :: IO
uglyLines = putStrLn . cs . mconcat
  $ [ "This is a long line apparently. "
  , "What do you think?"
  ]
niceLines :: IO
niceLines = putStrLn . cs . mconcat $
  [ "This is a long line apparently. "
  , "What do you think?"
  ]

Do blocks:

For do blocks, it is nicer to keep the do keyword on the same line as the operator:

someLines :: IO
someLines = forever $ do
  putStrLn "Hello"
  putStrLn "World"
someLines :: IO
someLines = forever $
  do
    putStrLn "Hello"
    putStrLn "World"

Indentation

Tabs are illegal. Use spaces for indenting. Indent your code blocks with 2 spaces. where clauses should be preceded by a blank line if they share the same indentation level with other code blocks.

Some examples:

sayHello :: IO ()
sayHello = do
  name <- getLine
  putStrLn $ greeting name
  
  where
    greeting name = "Hello, " ++ name ++ "!"

filter :: (a -> Bool) -> [a] -> [a]
filter _ [] = []
filter p (x:xs)
  | p x = x : filter p xs
  | otherwise = filter p xs

Alignment

Lines should only be aligned for indentation purposes. Alignment of later parts of a line should only be attempted if a tool supports doing this automatically. The reasoning being that manual alignment is easy to forget and tedious if an editor is not properly configured.

For example, stylish-haskell is a tool that can automatically align module imports and record field types. For this reason, it is considered acceptable to align these code blocks.

Blank Lines

One blank line between top-level definitions. No blank lines between type signatures and function definitions. Add one blank line between functions in a type class instance declaration if the function bodies are large. Add blank lines to logically split and group parts of a do block, when they are sufficiently large. Use your judgement.

For example:

sendStuff :: IO [Result]
sendStuff = do
  result <- send "This is not easy"
  result2 <- send "to read"
  skip 2 >> tryAgain 456
  result3 <- tryAndSend "since the code is very"
  tryAgain 324
  tryAgain 267
  result4 <- tryAndSend "dense"
  pure [result1, result2, result3, result4]

should would be easier to read if it was spaced:

sendStuff :: IO [Result]
sendStuff = do
  result <- send "This is not easy"
  result2 <- send "to read"

  skip 2 >> tryAgain 456

  result3 <- tryAndSend "since the code is very"

  tryAgain 324
  tryAgain 267

  result4 <- tryAndSend "dense"

  pure [result1, result2, result3, result4]

Whitespace

Surround binary operators with a single space on either side. Use your better judgement for the insertion of spaces around arithmetic operators, but always be consistent about whitespace on either side of a binary operator. Don't insert a space after a lambda.

Data Declarations

Align the constructors in a data type definition. Example:

data HttpException
  = InvalidStatusCode Int
  | MissingContentHeader

For short types with not many constructors, single-line formatting is also acceptable:

haskell
data Tree a = Branch !a !(Tree a) !(Tree a) | Leaf

Format records as follows:

data Person = Person
  { firstName :: !String  -- ^ First name
  , lastName  :: !String  -- ^ Last name
  , age       :: !Int     -- ^ Age
  } deriving (Eq, Show)

The deriving clause should be on a line by itself for regular data types, and on the same line as the closing bracket for records. For types deriving many type classes, use the following format:

data Person = Person
  { firstName :: !String  -- ^ First name
  , lastName  :: !String  -- ^ Last name
  , age       :: !Int     -- ^ Age
  } deriving
    ( Eq
    , Show
    , Generic
    , Read
    , SomeOtherTypeClass
    , AnotherTypeClass
    )

List Declarations

Align the elements in the list. Example:

exceptions =
  [ InvalidStatusCode
  , MissingContentHeader
  , InternalServerError
  ]

Pragmas

Put pragmas immediately following the function they apply to. Example:

id :: a -> a
id x = x
{-# INLINE id #-}

In the case of data type definitions you must put the pragma before the type it applies to. Example:

data Array e = Array
  {-# UNPACK #-} !Int
  !ByteArray

Hanging Lambdas

You may or may not indent the code following a "hanging" lambda. Use your judgement. Some examples:

bar :: IO ()
bar = forM_ [1, 2, 3] $ \n -> do
    putStrLn "Here comes a number!"
    print n

foo :: IO ()
foo = alloca 10 $ \a ->
  alloca 20 $ \b ->
  cFunction a b

Export Lists

Format export lists as follows:

module Data.Set
  (
    -- * The @Set@ type
    Set
  , empty
  , singleton

    -- * Querying
  , member
  ) where

If-then-else clauses

Generally, guards and pattern matches should be preferred over if-then-else clauses, where possible. Short cases should usually be put on a single line (when line length allows it).

You should be consistent with the 2-spaces indent rule, and the then and the else keyword should be aligned. Examples:

foo = do
  someCode
  
  if condition
    then someMoreCode
    else someAlternativeCode
foo = bar $ \qux -> if predicate qux
  then doSomethingSilly
  else someOtherCode

The same rule applies to nested do blocks:

foo = do
  instruction <- decodeInstruction
  skip <- load Memory.skip

  if skip == 0x0000
    then do
      execute instruction
      addCycles $ instructionCycles instruction
    else do
      store Memory.skip 0x0000
      addCycles 1

Case expressions

The alternatives in a case expression can be indented using the following style:

foobar = case something of
  Just j -> foo
  Nothing -> bar

Imports

Imports should be grouped in the following order:

  1. Standard library imports
  2. Related third party imports
  3. Local application/library specific imports

Put a blank line between each group of imports. The imports in each group should be sorted alphabetically, by module name.

Always use explicit import lists or qualified imports for standard and third party libraries. This makes the code more robust against changes in these libraries. This also makes it easier for other to locate the definition of a function. Exception: The Prelude.

Comments

Punctuation

Write proper sentences; start with a capital letter and use proper punctuation.

Top-Level Definitions

Comment every top level function (particularly exported functions), and provide a type signature; use Haddock syntax in the comments. Comment every exported data type. Function example:

-- | Send a message on a socket. The socket must be in a connected
-- state. Returns the number of bytes sent. Applications are
-- responsible for ensuring that all data has been sent.
send
  :: Socket  -- ^ Connected socket
  -> ByteString  -- ^ Data to send
  -> IO Int  -- ^ Bytes sent

For functions the documentation should give enough information to apply the function without looking at the function's definition.

Record example:

-- | Bla bla bla.
data Person = Person
  { age  :: !Int  -- ^ Age
  , name :: !String  -- ^ First name
  }

For fields that require longer comments format them like so:

data Record = Record
  { -- | This is a very very very long comment that is split over
    -- multiple lines.
    field1 :: !Text

    -- | This is a second very very very long comment that is split
    -- over multiple lines.
  , field2 :: !Int
  }

End-of-Line Comments

Separate end-of-line comments from the code using 2 spaces. Align comments for data type definitions. Some examples:

data Parser = Parser
  !Int  -- Current position
  !ByteString  -- Remaining input

foo :: Int -> Int
foo n = salt * 32 + 9
  where
    salt = 453645243  -- Magic hash salt.

Links

Use in-line links economically. You are encouraged to add links for API names. It is not necessary to add links for all API names in a Haddock comment. We therefore recommend adding a link to an API name
if:

  • The user might actually want to click on it for more information (in your judgment), and
  • Only for the first occurrence of each API name in the comment (don't bother repeating a link)

Naming

Use camel case (e.g. functionName) when naming functions and upper camel case (e.g. DataType) when naming data types.

For readability reasons, don't capitalize all letters when using an abbreviation. For example, write HttpServer instead of HTTPServer. Exception: Two letter abbreviations, e.g. IO.

Modules

Use singular when naming modules (e.g. use Data.Map and Data.ByteString.Internal instead of Data.Maps and Data.ByteString.Internals). Unless the module exports many functions of the same type (e.g. Document.Parsers, System.Exceptions, or App.Types).

Dealing with laziness

By default, use strict data types and lazy functions.

Data types

Constructor fields should be strict, unless there's an explicit reason to make them lazy. This avoids many common pitfalls caused by too much laziness and reduces the number of brain cycles the programmer has to spend thinking about evaluation order.

-- Good
data Point = Point
  { pointX :: !Double  -- ^ X coordinate
  , pointY :: !Double  -- ^ Y coordinate
  }
-- Bad
data Point = Point
  { pointX :: Double  -- ^ X coordinate
  , pointY :: Double  -- ^ Y coordinate
  }

Additionally, unpacking simple fields often improves performance and reduces memory usage:

data Point = Point
  { pointX :: {-# UNPACK #-} !Double  -- ^ X coordinate
  , pointY :: {-# UNPACK #-} !Double  -- ^ Y coordinate
  }

As an alternative to the UNPACK pragma, you can put

{-# OPTIONS_GHC -funbox-strict-fields #-}

at the top of the file. Including this flag in the file itself instead of e.g. in the Cabal file is preferable as the optimization will be applied even if someone compiles the file using other means (i.e. the optimization is attached to the source code it belongs to).

Note that -funbox-strict-fields applies to all strict fields, not just small fields (e.g. Double or Int). If you're using GHC 7.4 or later you can use NOUNPACK to selectively opt-out for the unpacking
enabled by -funbox-strict-fields.

Functions

Have function arguments be lazy unless you explicitly need them to be strict.

The most common case when you need strict function arguments is in recursion with an accumulator:

mysum :: [Int] -> Int
mysum = go 0
  where
    go !acc [] = acc
    go acc (x:xs) = go (acc + x) xs

Misc

Point-free style

If it makes code harder to read, avoid over-using point-free style.

-- Bad:
f = (g .) . h

Warnings

Code should be compilable with -Wall -Werror. There should be no warnings.

Last Author
etcinit
Projects
None
Subscribers
None