Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
249 lines (180 sloc) 6.54 KB

Haskell Style Guide

This is a short document describing the preferred coding style for this project. I've tried to cover the major areas of formatting and naming. When something isn't covered by this guide you should stay consistent with the code in the other modules.

Table of Contents

  1. Formatting
  2. Imports
  3. Comments
  4. Naming
  5. Misc

1. Formatting

Line Length

Maximum line length is 80 characters.

Indentation

Tabs are illegal. Use spaces for indenting. Indent your code blocks with 4 spaces. Indent guards with two spaces. Indent the where keyword two spaces to set it apart from the rest of the code and indent the definitions in a where clause 2 spaces. 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

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 functions bodies are large. Use your judgement.

Whitespace

Surround binary operators with a single space on either side. Use your better judgment 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 Tree a = Branch a (Tree a) (Tree a)
            | Leaf

or, if the declaration of the constructor is longer

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)

or

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

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 ->
          putStrLn "Here comes a number!"
          print n

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

2. Imports

Imports should be grouped and ordered from most specific to least specific, i.e.:

  1. same module hierarchy level
  2. local application/library specific imports
  3. related third party imports
  4. standard library 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. Exception: The Prelude.

3. Comments

Line Length

Maximum line length for comments is 70 characters. This increases readability as the eye has to travel back to the start of the next line.

Punctuation

Write proper sentences; start with a capital letter and use proper punctuation. Use a spell-checker if possible.

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. Some examples:

-- | 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

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

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

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.

4. Naming

Use mixed-case when naming functions and camel-case when naming data types. There are a few exceptions that are widely used.

  1. QuickCheck properties use a prop_ prefix.
  2. FFI wrapper use a c_ prefix.

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.

Ignored arguments

If a function takes several arguments and ignores some of them, do not use a simple _ as the pattern. Give it a descriptive name and precede it with an underscore, for example

foo :: Env -> Expr -> Int -> Int
foo _env expr accum = ...

5. Misc

Warnings

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

Invariants

Document invariants in the data type description. Wherever possible use smart constructors to enforce the invariant. For example:

-- | A binary tree.
--
-- INVARIANT: 'Empty' may only occur at the top-level.
data BinTree a
  = Empty
  | Branch (BinTree a) (BinTree a)
  | Leaf a

mkBranch :: BinTree a -> BinTree a -> BinTree a
mkBranch Empty t = t
mkBranch t Empty = t
mkBranch l r     = Branch l r

Type Signatures

Every top-level function should have a type signature. If a function has local functions, consider adding type signatures there, too. In Haskell'98 this is sometimes impossible, but with GHC you can use {-# LANGUAGE ScopedTypeVariables #-}.