---------------------------------------------------------------------------- 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 hierarchical 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. *** Minimize 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 be able 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 . Description goes here" No leading @ should be prefixed to the command (as this is meaningless in offline mode). The command should end in a full stop, followed by a sentence or two describing the command. Check in offline mode that 'help command' looks good.