---------------------------------------------------------------------------
---------------------------------------------------------------------------
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" (see "Good Programming Practice")
Put a haddock comment on top of every exported function and data type!
Make sure haddock accepts these comments by "make doc" after full
compilation with "make all".
---------------------------------------------------------------------------
---------------------------------------------------------------------------
All Haskell source files start with a haddock header of the form:
Module : <File name,
i.e. generated by \$Header\$>
Description : <Short text displayed on contents page>
Copyright : (c) <You> and Uni Bremen 2005
Maintainer : maeder@tzi.de
<module description starting at first column>
A possible compiler pragma (like {-# OPTIONS -cpp #-}) may precede
this header. The following hierarchical module name must of course
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 (indirectly) import
dependencies) the code becomes "non-portable".
The Dollar-Header-Dollar entry is automatically expanded by cvs (and will wrap
around). All other lines should not be longer than 80 (preferably 75)
characters to avoid wrapped lines (for casual readers)!
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.
The whole module should not be too long (about 400 lines)
---------------------------------------------------------------------------
---------------------------------------------------------------------------
In Haskell types start with capital and functions with lowercase
letters, so only avoid infix identifiers! (
i.e. "\\" at the end of a
line causes preprocessor problems and DrIFT has some limitation with
Names (especially global ones) should be descriptive and if you need
long names write them with underlines and lowercase letters or as
mixed case words. (but "tmp" is to be preferred over
"thisVariableIsATemporaryCounter")
Take care when defining your own symbolic identifiers. This should be
left to library writers only.
---------------------------------------------------------------------------
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."
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 to far to the right,
the code is unreadable anyway and needs to be decomposed.)
case <longer expression> of
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
Don't leave unused or commented-out code in your files!
---------------------------------------------------------------------------
Prefer case expressions over pattern binding declarations.
longFunctionName (Foo: _ : _) = e1
longFunctionName (Bar: _) = e2
longFunctionName arg = case arg of
For partial functions 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 formJust from
Data.Maybe) can be avoided by using the "maybe" function:
maybe (error "<ModuleName>.<function>") id $
Map.lookup key map
Do avoid mixing "let" and "where". (I prefer "let" and have auxiliary
function on the top-level that are not exported.) Export lists also
support the detection of unused functions.
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.
---------------------------------------------------------------------------
Many parentheses can be eliminated using the infix application operator "$"
with lowest priority. Try at least to avoid unnecessary parentheses in
standard infix expression.
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:
filter (const True) . map id $ case l of ...
However, be aware that $-terms cannot be composed further in infix
But the scope of an expression is also limited by the layout rule, so
it is usually save to use "$" on right hand sides.
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)
---------------------------------------------------------------------------
Use these only when "short and sweet". (I prefer map, filter, and foldr.)
---------------------------------------------------------------------------
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
Using type synonyms consistently is difficult over a longer time,
because this is not checked by the compiler.
Take care if your datatype 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 Mod f p = Mode BoxOrDiamond f p
data Tupel a b = Tupel a b | Undefined
data Tupel a b = Tupel a b
whenever an undefined result needs to be propagated
---------------------------------------------------------------------------
For (large) records avoid the use of the constructor directly and consider
that the order and number of fields may change.
Take care with depend polymorphic fields:
VariantWithTwo { field1 :: a
The type of a value v can not be changed by only setting field1:
Better construct a new value:
VariantWithTwo { field1 = f } -- leaving field2 undefined
Or use a polymorphic element that is instantiated by updating:
e = VariantWithTwo { field1 = [], field2 = [] }
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:
data Mode f p = Box { formula :: f, positions :: p }
| Diamond { formula :: f, positions :: p }
---------------------------------------------------------------------------
Try to strictly separate IO, Monad and pure (without do) function
programming (possibly via different modules).
on the (not always obvious) order of evaluation.
I.e. don't read and
because of lazy IO! (Writing is starting before reading is finished.)
---------------------------------------------------------------------------
Tracing is for debugging purposes only and should not be used as
feedback for the user. Clean code is not cluttered by trace calls.
---------------------------------------------------------------------------
Standard library modules like Char. List, Maybe, Monad, etc should be
imported by their hierarchical module name (so that haddock finds them):
The libraries for Set, Map and Rel are to be imported qualified:
Glasgow extensions and Classes
---------------------------------------------------------------------------
Stay away form 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 (multi-parameter type
classes), functional dependencies, undecidable and possibly incoherent
instances and then you are "in the wild" (according to SPJ).
---------------------------------------------------------------------------
---------------------------------------------------------------------------
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".
* 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
* people make fewer mistakes in consistent environments
* programmers have a common enemy :-)
* 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
Send comments to the "Maintainer" of this file