----------------------------------------------------------------------------
This document describes various style recommendations for the
lambdabot code. The goal is that all of the lambdabot source code should
respect this style guide, although it is not yet the case. You are therefore
encouraged to change source code such that it fits the style guide.
----------------------------------------------------------------------------
*** Import lists
{{{
module QuoteModule (
Type(..),
value1,
value2,
)
}}}
*** RCS tags
$Id .. $ tags should be removed, as we are using darcs now.
*** Order of imports
import statements should be ordered as so:
{{{
Local application
Local application qualified/as
Old-style Haskell2 modules
Data.*
Control.*
System.*
GHC.*
}}}
*** Function naming conventions
The convention for naming functions are as follows:
* Give meaningful names to functions. ``splitFirstWord'' is a good name,
but ``fooFunc'' is not.
* When composing multiple words into a function name, do not separate them
with a underscore (``_'') character. Just concatenate the words together.
* The first word is written in all lowercase. The words following are
capitalized.
Thus one should write:
splitFirstWord, join, breakOnGlue, debugStr, lookupSet, etc.
*** Use hierarchical modules
Old style non-hierarchical module imports should be replaced with
their hierachial module counterpart. The List module, as an example,
should be replaced with Data.List.
*** Use non-deprecated modules
Deprecated modules should be replaced by their non-deprecated
counterparts since it prevents bitrot of the source code.
*** Minimalize namespace
The namespace of a module should be minimized. Restrict imports such
that only used function calls and data types are imported. Furthermore
use qualified imports to split of the namespace in comprehensible parts.
-ddump-minimal-imports is useful for keeping a lid on this.
*** Provide explicit type signatures
We require all source code to build with -Werror. As a consequence
explicit type signatures for all functions should be provided.
*** Haddock documentation
We use Haddock as an API documentation tool. You should therefore
provide haddock comments for all exported functions, and preferably
for internal functions too. Proper documentation in Haddock will
provide other people an easier access to your modules, and will make
it easier to spot intent or catch errors.
*** Portability
Provide portable source code that works with ghc >= 6.2.2. Lambdabot
has a number of portability layer modules to ease the transition; the
most prominent being Map.hs, as it provides a portability layer to
Data.Map/Data.FiniteMap.
*** More references
We try to adopt the coding guidelines of the GHC project. Take a look at
the GHC libraries, in particular Data.Map, as the library modules follows
the guiding principles well.
*** Writing Module instances
moduleHelp should be provided for each command.
The help format is:
"command <arg1> <arg2>. Description goes here"
No leading @ should be prefixed to the command (as this is meaningless
in offline mode). The command should end in a fullstop, followed by a
sentence or two describing the command.
Check in offline mode that 'help command' looks good.