Difference between revisions of "Programming guidelines"

From HaskellWiki
Jump to navigation Jump to search
(programming guidelines proposal)
 
 
(40 intermediate revisions by 18 users not shown)
Line 1: Line 1:
 
 
 
Programming guidelines shall help to make the code of a project better
 
Programming guidelines shall help to make the code of a project better
 
readable and maintainable by the varying number of contributors.
 
readable and maintainable by the varying number of contributors.
   
 
It takes some programming experience to develop something like a
 
It takes some programming experience to develop something like a
personal "coding style" and guidelines only serve
+
personal "coding style" and guidelines only serve as rough shape for
as rough shape for code. Guidelines should be followed by all members
+
code. Guidelines should be followed by all members working on the
working on the project even if they prefer (or are already used to)
+
project even if they prefer (or are already used to) different
different guidelines.
+
guidelines.
   
  +
These guidelines have been originally set up for the [http://hets.eu hets-project] and are
In the following I will describe documentation, file format, naming
 
  +
now put on the [http://haskell.org/haskellwiki/ HaskellWiki] gradually
conventions and good programming practice (adapted form Matt's C/C++
 
  +
integrating parts of the old hawiki
Programming Guidelines and the Linux kernel coding style).
 
  +
entries [http://haskell.org/haskellwiki/Things_to_avoid 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
  +
[http://www.haskell.org/haskell-mode/ haskell mode].
   
  +
The following quote and links are taken from
=== Documentation ===
 
  +
HaskellStyle:
   
  +
:<i>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.
  +
</i>
   
  +
Some comments from the GHC team about their internal coding
Comments are to be written in application terms (i.e. user's point of
 
  +
standards can be found at
view). Don't use technical terms - that's what the code is for!
 
  +
http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions
   
  +
Also https://simon.peytonjones.org/publications-2000/#wearing-the-hair-shirt-a-retrospective-on-haskell-2003 contains some brief comments on syntax and style.
Comments should be written using correct spelling and grammar in complete
 
sentences with punctation (in English only).
 
   
  +
What now follows are descriptions of program documentation, file
"Generally, you want your comments to tell WHAT your code does, not HOW.
 
  +
format, naming conventions and good programming practice (adapted form
Also, try to avoid putting comments inside a function body: if the
 
  +
Matt's C/C++ Programming Guidelines and the Linux kernel coding
function is so complex that you need to separately comment parts of it,
 
  +
style).
you should probably" (... decompose it)
 
   
Put a haddock comment on top of every exported function and data type!
 
Make sure haddock accepts these comments.
 
   
  +
== 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!
=== File Format ===
 
   
  +
* Comments should be written using correct spelling and grammar in complete sentences with punctuation (in English only):
   
  +
::<i>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.]
All Haskell source files start with a haddock header of the form:
 
  +
</i>
   
  +
* Put a [http://haskell-haddock.readthedocs.io/en/latest/markup.html haddock comment] on top of every exported function and data type! Make sure haddock accepts these comments.
{- | <br>
 
Module : <File name, i.e. generated by \$Header\$> <br>
 
Description : <Short text displayed on contents page> <br>
 
Copyright : (c) <You> and <Your affiliation> <br>
 
License : similar to LGPL, see LICENSE.txt <br>
 
<br>
 
Maintainer : maeder@tzi.de <br>
 
Stability : provisional <br>
 
Portability : portable <br>
 
<br>
 
<module description starting at first column> <br>
 
-} <br>
 
   
  +
== File Format ==
   
  +
* All Haskell source files start with a haddock header of the form:
A possible compiler pragma (like {-# OPTIONS -cpp #-}) may precede
 
this header. The following hierarchical module name must of course
 
match the file name.
 
   
  +
:<haskell>
Make sure that the description is changed to meet the module (if the
 
  +
{- |
header was copied from elsewhere). Insert your email address as maintainer.
 
  +
Module : <File name or $Header$ to be replaced automatically>
  +
Description : <optional short text displayed on contents page>
  +
Copyright : (c) <Authors or Affiliations>
  +
License : <license>
   
  +
Maintainer : <email>
Try to write portable (Haskell98) code. If you (indirectly) import
 
  +
Stability : unstable | experimental | provisional | stable | frozen
a module that uses i.e. multi-parameter type classes and functional
 
dependencies the code becomes "non-portable (MPTC with FD)".
+
Portability : portable | non-portable (<reason>)
   
  +
<module description starting at first column>
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)
 
  +
</haskell>
characters to avoid wrapped lines (for casual readers)!
 
   
  +
:(the <code>\$Header\$</code> entry will be automatically expanded.)
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.
 
   
  +
:A possible compiler pragma (like <code>{-# LANGUAGE CPP #-}</code>) may precede this header. The following hierarchical module name must, of course, match the file name.
(custom-set-variables '(indent-tabs-mode nil))
 
   
  +
* Make sure that the description is changed to meet the module (if the header was copied from elsewhere). Insert your email address as maintainer.
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.
 
   
  +
* Try to write portable ([[Language_and_library_specification#The_Haskell_2010_report|Haskell 2010]]) code. If you use e.g. [[MPTC|multi-parameter type classes]] (MTPC) and [[Functional dependencies|functional dependencies]] (FD) the code becomes [https://mail.haskell.org/pipermail/haskell-prime/2006-February/000609.html "non-portable (MPTC with FD)"].
The whole module should not be too long (about 400 lines)
 
   
  +
* Lines should not be longer than 80 (preferably 75) characters. Code with short lines reads casually and easier to understand. If the expression is longer than 80 lines, try to structure & rewrite the code in a more expressive way. 80 character lines is considered good practice across IT industry and supported in all cases.
   
  +
* Don't leave trailing white space in your code in every line.
=== Naming Conventions ===
 
   
  +
* 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 <tt>~/.emacs</tt> file:
   
  +
: <code>(custom-set-variables '(indent-tabs-mode nil))</code>
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 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. <code>#endif</code> without newline). Emacs usually asks for a final newline.
(The infix identifier "\\" at the end of a line causes cpp preprocessor
 
problems.)
 
   
  +
* You may use http://hackage.haskell.org/package/scan to check your file format.
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")
 
   
  +
* The whole module should not be too long (about 400 lines)
   
  +
Please have a look at the [http://haskell-haddock.readthedocs.io/en/latest/markup.html#the-module-description Haddock module header documentation].
=== Good Programming Practice ===
 
   
  +
== 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.
"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."
 
   
  +
:(The infix identifier <code>"\\"</code> at the end of a line causes CPP preprocessor problems.)
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.
 
   
  +
* Names (especially global ones) should be descriptive. If you need long names write them in [[wiki:CamelCase|lowerCamelCase]]. Laconic names are preferred.
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.
 
   
  +
* Similarly, type, type class, and constructor names are written using [[wiki:CamelCase|UpperCamelCase]].
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.)
 
   
  +
* In the standard libraries, some parts of Haskell code use [https://en.wikipedia.org/wiki/Snake_case snake_case] for long identifiers to better reflect names given with hyphens in the required documentation. If used in outer code - such names should be transliterated to camlCase identifiers possibly adding a (consistent) suffix or prefix to avoid conflicts with keywords. And instead of a recurring prefix or suffix, you may consider using qualified imports and names.
Bad:
 
case foo of Foo -> "Foo"
 
Bar -> "Bar"
 
Good:
 
case <longer expression> of
 
Foo -> "Foo"
 
Bar -> "Bar"
 
   
  +
== Good Programming Practice ==
Avoid the notation with braces and semicolons since the layout rule
 
forces you to properly align your alternatives.
 
   
  +
::<i>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.
Respect compiler warnings. Supply type signatures, avoid shadowing and
 
  +
</i>
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.
 
   
  +
* Most Haskell functions should be at most a few lines, only case expressions over large data types (that should be avoided, too) may need corresponding space.
Don't leave unused or commented-out code in your files! Readers don't
 
know what to think of it.
 
   
  +
* For lambda expressions, write <code>\ t -> …</code> instead of <code>\t -> …</code>.
   
  +
* 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.
==== Case expressions ====
 
   
  +
* It's not fixed how deep you indent (4 or 8 chars). You can break the line after <code>do</code>, <code>let</code>, <code>where</code>, and <code>case … of …</code>. 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.)
Prefer case expressions over pattern binding declarations.
 
   
  +
::Bad:
Not always nice:
 
  +
::<haskell>
longFunctionName (Foo: _ : _) = e1
 
  +
case foo of Foo -> "Foo"
longFunctionName (Bar: _) = e2
 
  +
Bar -> "Bar"
  +
</haskell>
   
  +
::Good:
Better (I think):
 
  +
::<haskell>
longFunctionName arg = case arg of
 
  +
case <longer expression> of
Foo : _ : _ -> e1
 
Bar : _ -> e2
+
Foo -> "Foo"
  +
Bar -> "Bar"
_ -> error "ProgrammingGuidelines.longFunctionName"
 
  +
</haskell>
   
  +
:Avoid the notation with braces and semicolons since the layout rule forces you to properly align your alternatives.
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.
 
   
  +
* 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 <code>error</code> with a fixed string <code>"<ModuleName>.<function>"</code> 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.
Usually a case statement (and the import of isJust and fromJust from
 
Data.Maybe) can be avoided by using the "maybe" function:
 
   
  +
* Don't leave unused or commented-out code in your files! Readers don't know what to think of it.
maybe (error "<ModuleName>.<function>") id $ Map.lookup key map
 
   
  +
=== Partial functions ===
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.
 
   
  +
* 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 <code>head</code> should be used with care or (even better) be made obsolete by a case statement.
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.
 
   
  +
* Usually a case-expression (and the import of <code>isJust</code> and <code>fromJust</code> from <code>Data.[[Maybe]]</code>) can be avoided by using the <code>maybe</code> function:
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.
 
   
  +
:<haskell>
  +
maybe (error "<ModuleName>.<function>") id $ Map.lookup key map
  +
</haskell>
   
  +
: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.
==== Application notation ====
 
   
  +
=== Let or where expressions ===
   
  +
Do avoid mixing and nesting <code>let</code> and <code>where</code>. (I prefer the expression-stylistic <code>let</code>.) Use auxiliary top-level functions that you do not export. Export lists also support the detection of unused functions.
Many parentheses can be eliminated using the infix application operator "$"
 
with lowest priority. Try at least to avoid unnecessary parentheses in
 
standard infix expression.
 
   
  +
=== Code reuse ===
f x : g x ++ h x
 
   
  +
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.
a == 1 && b == 1 || a == 0 && b == 0
 
   
  +
=== Application notation ===
Rather than putting a large final argument in parentheses (with a
 
distant closing one) consider using "$" instead.
 
   
  +
Many parentheses can be eliminated using the infix application operator <code>$</code> with lowest priority. Try at least to avoid unnecessary parentheses in standard infix expression.
"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".
 
  +
<haskell>
  +
f x : g x ++ h x
  +
  +
a == 1 && b == 1 || a == 0 && b == 0
  +
</haskell>
  +
  +
Rather than putting a large final argument in parentheses (with a distant closing one) consider using <code>$</code> instead.
  +
  +
* <code>f (g x)</code> becomes <code>f $ g x</code> and consecutive applications
  +
* <code>f (g (h x))</code> can be written as <code>f $ g $ h x</code> or <code>f . g $ h x</code>.
   
 
A function definition like
 
A function definition like
"f x = g $ h x" can be abbreviated to "f = g . h".
+
<code>f x = g $ h x</code> can be abbreviated to <code>f = g . h</code>.
   
Note that the final argument may even be an infix- or case expression:
+
Note that the final argument may even be an infix or case-expression:
   
  +
:<haskell>
map id $ c : l
 
  +
map id $ c : l
   
filter (const True) . map id $ case l of ...
+
filter (const True) . map id $ case l of
  +
</haskell>
   
However, be aware that $-terms cannot be composed further in infix
+
However, be aware that <code>$</code>-terms cannot be composed further in infix expressions.
expressions.
 
   
 
Probably wrong:
 
Probably wrong:
  +
:<haskell>
f $ x ++ g $ x
 
  +
f $ x ++ g $ x
  +
</haskell>
   
But the scope of an expression is also limited by the layout rule, so
+
But the scope of an expression is also limited by the layout rule, so it is usually safe to use <code>$</code> on right hand sides:
it is usually save to use "$" on right hand sides.
 
   
Ok:
+
:Ok:
  +
::<haskell>
do y <- f $ l
 
++
+
do f $ l
  +
++
do y <- g $ l
 
  +
do g $ l
  +
</haskell>
   
Of course "$" can not be used in types. GHC has also some primitive
+
Of course <code>$</code> can not be used in types. GHC has also some primitive functions involving the kind <code>#</code> that cannot be applied using <code>$</code>.
functions involving the kind "#" that cannot be applied using "$".
 
   
Last warning: always leave spaces around "$" (and other mixfix
+
Last warning: always leave spaces around <code>$</code> (and other mixfix operators) since a clash with template haskell is possible.
operators) since a clash with template haskell is possible.
 
   
  +
=== List Comprehensions ===
(Also write "\ t" instead of "\t" in lambda expressions)
 
   
  +
Use these only when "short and sweet". Prefer <code>map</code>, <code>filter</code>, and <code>foldr</code>!
   
  +
Instead of:
==== List Comprehensions ====
 
   
  +
:<haskell>
Use these only when "short and sweet". (I prefer map, filter, and foldr.)
 
  +
[toUpper c | c <- s]
  +
</haskell>
   
  +
write:
   
  +
:<haskell>
==== Types ====
 
  +
map toUpper s
  +
</haskell>
   
  +
Consider:
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.
 
   
  +
:<haskell>
Using type synonyms consistently is difficult over a longer time,
 
  +
[toUpper c | s <- strings, c <- s]
because this is not checked by the compiler. (The types shown by
 
  +
</haskell>
the compiler may be unpredictable: i.e. FilePath, String or [Char])
 
   
  +
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 <code>s</code> and <code>c</code> are used.
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.
 
   
  +
In contrast to that the following can't be clearer:
Bad (to handle arguments in sync):
 
   
  +
:<haskell>
data Mode f p = Box f p | Diamond f p
 
  +
map toUpper (concat strings)
  +
</haskell>
   
  +
When using higher-order functions you can switch easier to data structures different from list. Compare:
Good (to handle arguments only once):
 
   
  +
:<haskell>
data BoxOrDiamond = Box | Diamond
 
  +
map (1+) list
  +
</haskell>
   
  +
and:
data Mode f p = Mode BoxOrDiamond f p
 
   
  +
:<haskell>
  +
Set.map (1+) set
  +
</haskell>
   
  +
=== Records ===
Consider (bad):
 
   
  +
For (large) records avoid the use of the constructor directly and remember that the order and number of fields may change.
data Tupel a b = Tupel a b | Undefined
 
   
  +
Take care with (the rare case of) depend polymorphic fields:
versus (better):
 
   
  +
:<haskell>
data Tupel a b = Tupel a b
 
  +
data Fields a = VariantWithTwo
  +
{ field1 :: a
  +
, field2 :: a }
  +
</haskell>
   
  +
The type of a value <code>v</code> can not be changed by only setting <code>field1</code>:
and using:
 
   
  +
:<haskell>
Maybe (Tupel a b)
 
  +
v { field1 = f }
  +
</haskell>
   
  +
Better construct a new value:
(or another monad) whenever an undefined result needs to be propagated
 
   
  +
:<haskell>
  +
VariantWithTwo { field1 = f } -- leaving field2 undefined
  +
</haskell>
   
  +
Or use a polymorphic element that is instantiated by updating:
==== Records ====
 
   
  +
:<haskell>
For (large) records avoid the use of the constructor directly and
 
  +
empty = VariantWithTwo { field1 = [], field2 = [] }
remember that the order and number of fields may change.
 
   
  +
empty { field1 = [f] }
Take care with (the rare case of) depend polymorphic fields:
 
  +
</haskell>
   
  +
Several variants with identical fields may avoid some code duplication when selecting and updating, though possibly not in a few depended polymorphic cases.
data Fields a = VariantWithTwo
 
{ field1 :: a
 
, field2 :: a }
 
   
  +
However, I doubt if the following is a really good alternative to the above data <code>Mode</code> with data <code>BoxOrDiamond</code>.
The type of a value v can not be changed by only setting field1:
 
   
  +
:<haskell>
v { field1 = f }
 
  +
data Mode f p =
  +
Box { formula :: f, positions :: p }
  +
| Diamond { formula :: f, positions :: p }
  +
</haskell>
   
  +
=== Types ===
Better construct a new value:
 
   
  +
* 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.
VariantWithTwo { field1 = f } -- leaving field2 undefined
 
   
  +
* 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. <code>FilePath</code>, <code>String</code> or <code>[Char]</code>.)
Or use a polymorphic element that is instantiated by updating:
 
   
  +
* 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.
empty = VariantWithTwo { field1 = [], field2 = [] }
 
   
  +
:Bad (to handle arguments in sync):
empty { field1 = [f] }
 
   
  +
::<haskell>
Several variants with identical fields may avoid some code duplication
 
  +
data Mode f p = Box f p | Diamond f p
when selecting and updating, though possibly not in a few
 
  +
</haskell>
depended polymorphic cases.
 
   
  +
:Good (to handle arguments only once):
However, I doubt if the following is a really good alternative to the
 
above data Mode with data BoxOrDiamond.
 
   
  +
::<haskell>
  +
data BoxOrDiamond = Box | Diamond
   
data Mode f p =
+
data Mode f p = Mode BoxOrDiamond f p
  +
</haskell>
Box { formula :: f, positions :: p }
 
| Diamond { formula :: f, positions :: p }
 
   
   
  +
* Consider (bad):
==== IO ====
 
   
  +
::<haskell>
Try to strictly separate IO, Monad and pure (without do) function
 
  +
data Tuple a b = Tuple a b | Undefined
programming (possibly via separate modules).
 
  +
</haskell>
   
  +
:versus (better):
Bad:
 
x <- return y
 
...
 
   
  +
::<haskell>
Good:
 
  +
data Tuple a b = Tuple a b
let x = y
 
  +
</haskell>
...
 
   
  +
:and using:
   
  +
::<haskell>
Don't use Prelude.interact and make sure your program does not depend
 
  +
Maybe (Tuple a b)
on the (not always obvious) order of evaluation. I.e. don't read and
 
  +
</haskell>
write to the same file:
 
   
  +
:(or another monad) whenever an undefined result needs to be propagated
This will fail:
 
   
  +
=== I/O ===
do s <- readFile f
 
writeFile f $ 'a' : s
 
   
  +
Try to strictly separate monadic I/O and pure (without <code>do</code>) function programming (possibly via separate modules).
because of lazy IO! (Writing is starting before reading is finished.)
 
   
  +
:Bad:
   
  +
::<haskell>
==== Trace ====
 
  +
x <- return y
  +
...
  +
</haskell>
   
  +
:Good:
Tracing is for debugging purposes only and should not be used as
 
feedback for the user. Clean code is not cluttered by trace calls.
 
   
  +
::<haskell>
  +
let x = y
  +
...
  +
</haskell>
   
  +
Don't use <code>Prelude.interact</code> 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!
==== Imports ====
 
   
  +
This will fail:
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):
 
   
  +
:<haskell>
import Data.List
 
  +
do s <- readFile f
import Control.Monad
 
  +
writeFile f $ 'a' : s
import System.Environment
 
  +
</haskell>
   
  +
because of lazy I/O! (Writing is starting before reading is finished).
The libraries for Set and Map are to be imported qualified:
 
   
  +
=== Imports ===
import qualified Data.Set as Set
 
import qualified Data.Map as Map
 
   
  +
Standard library modules like <code>Char</code>, <code>List</code>, <code>Maybe</code>, <code>Monad</code>, etc should be imported by their hierarchical module name, i.e. the base package (so that haddock finds them):
   
  +
:<haskell>
==== Glasgow extensions and Classes ====
 
  +
import Data.List
  +
import Control.Monad
  +
import System.Environment
  +
</haskell>
   
  +
The libraries for <code>Set</code> and <code>Map</code> are to be imported qualified:
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 (FD), undecidable and possibly incoherent
 
instances and then you are "in the wild" (according to SPJ).
 
   
  +
:<haskell>
  +
import qualified Data.Set as Set
  +
import qualified Data.Map as Map
  +
</haskell>
   
=== Final remarks ===
 
   
  +
=== Implementation-specific extensions and classes ===
Despite guidelines, writing "correct code" (without formal proof
 
  +
support yet) still remains the major challenge. As motivation to
 
  +
[[Use of language extensions|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 (multi-parameter type classes), functional dependencies (FD), undecidable and possibly incoherent instances and then you are "in the wild" (according to SPJ).
follow these guidelines consider the points that are from the "C++
 
  +
Coding Standard", where I replaced "C++" with "Haskell".
 
  +
=== 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.
  +
  +
== Style in other languages ==
  +
  +
* [http://www.cs.caltech.edu/~cs20/a/style.html OCaml style]
  +
  +
== 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:
 
Good Points:
   
* programmers can go into any code and figure out what's going on
+
* programmers can go into any code and figure out what's going on
   
* new people can get up to speed quickly
+
* new people can get up to speed quickly
   
* people new to Haskell are spared the need to develop a personal
+
* people new to Haskell are spared the need to develop a personal style and defend it to the death
style and defend it to the death
 
   
* people new to Haskell are spared making the same mistakes over
+
* people new to Haskell are spared making the same mistakes over and over again
and over again
 
   
* people make fewer mistakes in consistent environments
+
* people make fewer mistakes in consistent environments
   
* programmers have a common enemy :-)
+
* programmers have a common enemy :-)
   
 
Bad Points:
 
Bad Points:
   
* the standard is usually stupid because it was made by someone
+
* the standard is usually stupid because it was made by someone who doesn't understand Haskell
  +
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
  +
  +
== Other guidelines ==
  +
  +
[https://www.cse.unsw.edu.au/~cs3161/15s2/StyleGuide.html COMP3161]
  +
  +
[http://docs.ganeti.org/ganeti/2.13/html/dev-codestyle.html#haskell Google's ganeti]
   
  +
[https://kowainik.github.io/posts/2019-02-06-style-guide kowainik]
* the standard is usually stupid because it's not what I do
 
   
  +
[https://github.com/Soostone/style-guides/blob/master/haskell-style-guide.md Soostone]
* standards reduce creativity
 
   
  +
[https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md tibbe]
* standards are unnecessary as long as people are consistent
 
   
  +
[https://github.com/tweag/guides/blob/master/style/Haskell.md tweag]
* standards enforce too much structure
 
   
  +
[[Category:Style]]
* people ignore standards anyway
 

Latest revision as of 09:36, 10 August 2022

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 hets-project and are now put on the HaskellWiki 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 at http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions

Also https://simon.peytonjones.org/publications-2000/#wearing-the-hair-shirt-a-retrospective-on-haskell-2003 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).


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 punctuation (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.

File Format

  • All Haskell source files start with a haddock header of the form:
{- |
Module      :  <File name or $Header$ to be replaced automatically>
Description :  <optional short text displayed on contents page>
Copyright   :  (c) <Authors or Affiliations>
License     :  <license>

Maintainer  :  <email>
Stability   :  unstable | experimental | provisional | stable | frozen
Portability :  portable | non-portable (<reason>)

<module description starting at first column>
-}
(the \$Header\$ entry will be automatically expanded.)
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.
  • Lines should not be longer than 80 (preferably 75) characters. Code with short lines reads casually and easier to understand. If the expression is longer than 80 lines, try to structure & rewrite the code in a more expressive way. 80 character lines is considered good practice across IT industry and supported in all cases.
  • 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.
  • The whole module should not be too long (about 400 lines)

Please have a look at the Haddock module header documentation.

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. If you need long names write them in lowerCamelCase. Laconic names are preferred.
  • Similarly, type, type class, and constructor names are written using UpperCamelCase.
  • In the standard libraries, some parts of Haskell code use snake_case for long identifiers to better reflect names given with hyphens in the required documentation. If used in outer code - such names should be transliterated to camlCase identifiers possibly adding a (consistent) suffix or prefix to avoid conflicts with keywords. And instead of a recurring prefix or suffix, you may consider using qualified imports and names.

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 expressions over large data types (that should be avoided, too) may need corresponding space.
  • For lambda expressions, write \ t -> … instead of \t -> ….
  • 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.

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-expression (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.

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.

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.

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.

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

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 }

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

I/O

Try to strictly separate monadic I/O 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 I/O! (Writing is starting before reading is finished).

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


Implementation-specific 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 (multi-parameter type classes), functional dependencies (FD), undecidable and possibly incoherent instances and then you are "in the wild" (according to SPJ).

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.

Style in other languages

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

Other guidelines

COMP3161

Google's ganeti

kowainik

Soostone

tibbe

tweag