Programming guidelines

Programming guidelines shall help to make the code of a project better readable and maintainable
by the varying number of contributors.

It takes some programming experience to develop something like a

personal "coding style" and guidelines only serve as rough shape
for code. Guidelines should be followed by all members working on
the project even if they prefer (or are already used to) different
guidelines.
These guidelines have been originally set up for the hetsproject hets-project and are now put on theHaskellWiki gradually
integrating parts of the old hawiki entries ThingsToAvoid and
HaskellStyle (hopefully not hurting someone's copyrights). The
other related entry TipsAndTricks treats more specific points that
are left out here,
Surely some style choices are a bit arbitrary (or "religious") and too
restrictive with respect to language extensions. Nevertheless I hope
to keep up these guidelines (at least as a basis) for our project in
order to avoid maintaining diverging guidelines. Of course I want to
supply - partly tool-dependent - reasons for certain decisions and
also show alternatives by possibly bad examples. At the time of
writing I use ghc-6.4.1, haddock-0.7 and (GNU-) emacs with the
latest haskell mode.
The following quote and links are taken from HaskellStyle:
We all have our own ideas about good Haskell style. There's More
Than One Way To Do It. But some ways are better than others.
Some comments from the GHC team about their internal coding
standards can be found
athttp://hackage.haskell.org/trac/ghc/wiki/WorkingConventions
Also http://research.microsoft.com/~simonpj/papers/haskellretrospective/ contains some brief comments on syntax and style,
What now follows are descriptions of program documentation, file
format, naming conventions and good programming practice
(adapted form Matt's C/C++ Programming Guidelines and the Linux
kernel coding style).

Contents
[hide]

1 Docume
ntation
2 File
Format
3 Naming
Conventio
ns
4 Good
Programm
ing
Practice
4.1 Partial
functions
4.2 Let or
where
expression
s
4.3 Code
reuse
4.4 Applic
ation
notation
4.5 List
Comprehe
nsions
4.6 Types
4.7 Record
s
4.8 IO
4.9 Trace
4.10 Impo
rts
4.11 Glasg
ow
extensions
and
Classes
5 Style in
other
languages
6 Final
remarks

1 Documentation
Comments are to be written in application terms (i.e. user's point of
view). Don't use technical terms - that's what the code is for!
Comments should be written using correct spelling and grammar in
complete sentences with punctation (in English only).

"Generally, you want your comments to tell WHAT your code does,
not HOW. Also, try to avoid putting comments inside a function
body: if the function is so complex that you need to separately
comment parts of it, you should probably" (... decompose it)
Put a haddock comment on top of every exported function and data
type! Make sure haddock accepts these comments.
2 File Format
All Haskell source
{- |
Module
:
automatically>
Description :
contents page>
Copyright
:
License
:

files start with a haddock header of the form:

<File name or $Header$ to be replaced
<optional short text displayed on
(c) <Authors or Affiliations>
<license>

Maintainer : <email>
Stability
: unstable | experimental | provisional |
stable | frozen
Portability : portable | non-portable (<reason>)
<module description starting at first column>
-}
A possible compiler pragma (like {-# LANGUAGE CPP #-}) may
precede this header. The following hierarchical module name must
of course match the file name.
Make sure that the description is changed to meet the module (if
the header was copied from elsewhere). Insert your email address
as maintainer.
Try to write portable (Haskell98) code. If you use e.g. multiparameter type classes and functional dependencies the code
becomes "non-portable (MPTC with FD)".
The \$Header\$ entry will be automatically expanded.
Lines should not be longer than 80 (preferably 75) characters to
avoid wrapped lines (for casual readers)!
Don't leave trailing white space in your code in every line.
Expand all your tabs to spaces to avoid the danger of wrongly
expanding them (or a different display of tabs versus eight spaces).
Possibly put something like the following in your ~/.emacs file.
(custom-set-variables '(indent-tabs-mode nil))

The last character in your file should be a newline! Under solaris

you'll get a warning if this is not the case and sometimes last lines
without newlines are ignored (i.e. "#endif" without newline). Emacs
usually asks for a final newline.
You may use http://hackage.haskell.org/package/scan to check your
file format.
The whole module should not be too long (about 400 lines)
3 Naming Conventions
In Haskell types start with capital and functions with lowercase
letters, so only avoid infix identifiers! Defining symbolic infix
identifiers should be left to library writers only.
(The infix identifier "\\" at the end of a line causes cpp preprocessor
problems.)
Names (especially global ones) should be descriptive and if you
need long names write them as mixed case words (aka camelCase).
(but "tmp" is to be preferred over
"thisVariableIsATemporaryCounter")
Also in the standard libraries, function names with multiple words
are written using the camelCase convention. Similarly, type,
typeclass and constructor names are written using the StudlyCaps
convention.
Some parts of our code use underlines (without unnecessary
uppercase letters) for long identifiers to better reflect names given
with hyphens in the requirement documentation. Also such names
should be transliterated to camlCase identifiers possibly adding a
(consistent) suffix or prefix to avoid conflicts with keywords.
However, instead of a recurring prefix or suffix you may consider to
use qualified imports and names.
4 Good Programming Practice
"Functions should be short and sweet, and do just one thing. They
should fit on one or two screenfuls of text (the ISO/ANSI screen size
is 80x24, as we all know), and do one thing and do that well."
Most haskell functions should be at most a few lines, only case
expression over large data types (that should be avoided, too) may
need corresponding space.
The code should be succinct (though not obfuscated), readable and
easy to maintain (after unforeseeable changes). Don't exploit exotic
language features without good reason.
It's not fixed how deep you indent (4 or 8 chars). You can break the
line after "do", "let", "where", and "case .. of". Make sure that
renamings don't destroy your layout. (If you get too far to the right,
the code is unreadable anyway and needs to be decomposed.)
Bad:

case foo of Foo -> "Foo"

Bar -> "Bar"
Good:
case <longer expression> of
Foo -> "Foo"
Bar -> "Bar"
Avoid the notation with braces and semicolons since the layout rule
forces you to properly align your alternatives.
Respect compiler warnings. Supply type signatures, avoid
shadowing and unused variables. Particularly avoid non-exhaustive
and overlapping patterns. Missing unreachable cases can be filled in
using "error" with a fixed string "<ModuleName>.<function>" to
indicate the error position (in case the impossible should happen).
Don't invest time to "show" the offending value, only do this
temporarily when debugging the code.
Don't leave unused or commented-out code in your files! Readers
don't know what to think of it.
4.1 Partial functions

For partial functions do document their preconditions (if not

obvious) and make sure that partial functions are only called when
preconditions are obviously fulfilled (i.e. by a case statement or a
previous test). Particularly the call of "head" should be used with
care or (even better) be made obsolete by a case statement.
Usually a case statement (and the import of isJust and fromJust from
Data.Maybe) can be avoided by using the "maybe" function:
maybe (error "<ModuleName>.<function>") id $
Map.lookup key map
Generally we require you to be more explicit about failure cases.
Surely a missing (or an irrefutable) pattern would precisely report
the position of a runtime error, but these are not so obvious when
reading the code.
4.2 Let or where expressions

Do avoid mixing and nesting "let" and "where". (I prefer the

expression-stylistic "let".) Use auxiliary top-level functions that you
do not export. Export lists also support the detection of unused
functions.
4.3 Code reuse

If you notice that you're doing the same task again, try to
generalize it in order to avoid duplicate code. It is frustrating to
change the same error in several places.

4.4 Application notation

Many parentheses can be eliminated using the infix application

operator "$" with lowest priority. Try at least to avoid unnecessary
parentheses in standard infix expression.
f x : g x ++ h x
a == 1 && b == 1 || a == 0 && b == 0
Rather than putting a large final argument in parentheses (with a
distant closing one) consider using "$" instead.
"f (g x)" becomes "f $ g x" and consecutive applications "f (g (h x))"
can be written as "f $ g $ h x" or "f . g $ h x".
A function definition like "f x = g $ h x" can be abbreviated to "f = g
. h".
Note that the final argument may even be an infix- or case
expression:
map id $ c : l
filter (const True) . map id $ case l of ...
However, be aware that $-terms cannot be composed further in
infix expressions.
Probably wrong:
f $ x ++ g $ x
But the scope of an expression is also limited by the layout rule, so
it is usually safe to use "$" on right hand sides.
Ok:
do f $ l
++
do g $ l
Of course "$" can not be used in types. GHC has also some
primitive functions involving the kind "#" that cannot be applied
using "$".
Last warning: always leave spaces around "$" (and other mixfix
operators) since a clash with template haskell is possible.
(Also write "\ t" instead of "\t" in lambda expressions)
4.5 List Comprehensions

Use these only when "short and sweet". Prefer map, filter, and foldr!
Instead of:
[toUpper c | c <- s]
write:
map toUpper s
Consider:

[toUpper c | s <- strings, c <- s]

Here it takes some time for the reader to find out which value
depends on what other value and it is not so clear how many times
the interim values s and c are used. In contrast to that the following
can't be clearer:
map toUpper (concat strings)
When using higher order functions you can switch easier to data
structures different from list. Compare:
map (1+) list
and:
Set.map (1+) set
4.6 Types

Prefer proper data types over type synonyms or tuples even if you
have to do more constructing and unpacking. This will make it
easier to supply class instances later on. Don't put class constraints
on a data type, constraints belong only to the functions that
manipulate the data.
Using type synonyms consistently is difficult over a longer time,
because this is not checked by the compiler. (The types shown by
the compiler may be unpredictable: i.e. FilePath, String or [Char])
Take care if your data type has many variants (unless it is an
enumeration type.) Don't repeat common parts in every variant
since this will cause code duplication.
Bad (to handle arguments in sync):
data Mode f p = Box f p | Diamond f p
Good (to handle arguments only once):
data BoxOrDiamond = Box | Diamond
data Mode f p = Mode BoxOrDiamond f p
Consider (bad):
data Tuple a b = Tuple a b | Undefined
versus (better):
data Tuple a b = Tuple a b
and using:
Maybe (Tuple a b)
(or another monad) whenever an undefined result needs to be
propagated

4.7 Records

For (large) records avoid the use of the constructor directly and
remember that the order and number of fields may change.
Take care with (the rare case of) depend polymorphic fields:
data Fields a = VariantWithTwo
{ field1 :: a
, field2 :: a }
The type of a value v can not be changed by only setting field1:
v { field1 = f }
Better construct a new value:
VariantWithTwo { field1 = f } -- leaving field2
undefined
Or use a polymorphic element that is instantiated by updating:
empty = VariantWithTwo { field1 = [], field2 = [] }
empty { field1 = [f] }
Several variants with identical fields may avoid some code
duplication when selecting and updating, though possibly not in a
few depended polymorphic cases.
However, I doubt if the following is a really good alternative to the
above data Mode with data BoxOrDiamond.
data Mode f p =
Box
{ formula :: f, positions :: p }
| Diamond { formula :: f, positions :: p }
4.8 IO

Try to strictly separate IO, Monad and pure (without do) function
programming (possibly via separate modules).
Bad:
x <- return y
...
Good:
let x = y
...
Don't use Prelude.interact and make sure your program does not
depend on the (not always obvious) order of evaluation. E.g. don't
read and write to the same file:
This will fail:
do s <- readFile f

writeFile f $ 'a' : s
because of lazy IO! (Writing is starting before reading is finished.)
4.9 Trace

Tracing is for debugging purposes only and should not be used as

feedback for the user. Clean code is not cluttered by trace calls.
4.10 Imports

Standard library modules like Char. List, Maybe, Monad, etc should
be imported by their hierarchical module name, i.e. the base
package (so that haddock finds them):
import Data.List
import Control.Monad
import System.Environment
The libraries for Set and Map are to be imported qualified:
import qualified Data.Set as Set
import qualified Data.Map as Map
4.11 Glasgow extensions and Classes

Stay away from extensions as long as possible. Also use classes

with care because soon the desire for overlapping instances (like for
lists and strings) may arise. Then you may want MPTC (multiparameter type classes), functional dependencies (FD), undecidable
and possibly incoherent instances and then you are "in the wild"
(according to SPJ).
5 Style in other languages
OCaml style
6 Final remarks
Despite guidelines, writing "correct code" (without formal proof
support yet) still remains the major challenge. As motivation to
follow these guidelines consider the points that are from the "C++
Coding Standard", where I replaced "C++" with "Haskell".
Good Points:
programmers can go into any code and figure out what's going on
new people can get up to speed quickly
people new to Haskell are spared the need to develop a personal
style and defend it to the death
people new to Haskell are spared making the same mistakes over
and over again
people make fewer mistakes in consistent environments
programmers have a common enemy :-)
Bad Points:
the standard is usually stupid because it was made by someone
who doesn't understand Haskell

the standard is usually stupid because it's not what I do

standards reduce creativity
standards are unnecessary as long as people are consistent
standards enforce too much structure
people ignore standards anyway