• Derived from
  • Haskell - Programming guidelines
  • Haskell Style Guide
• Cross-link
  • Haddock examples

For source code, the line length is up to 80 characters, at the maximum.

• Example:

  ------------------------------------------------------------------------------ |---...
   
  ...
   
  instance Formatting a => Formatting (Ds.Tree a) where
      format t = format' (Indent []) t where
          format' :: Formatting a => Indent -> (Ds.Tree a) -> String
          format' ind (Ds.Node s tl) = 
              (format ind) ++ 
              (format s) ++ 
              "\n" ++ 
              (prettyFormatTL' (pushIndent ind Continuing) tl)
          prettyFormatTL' :: Formatting a => Indent -> [Ds.Tree a] -> String
          prettyFormatTL' _ ([])      = 
              ""
          prettyFormatTL' ind (tn:[])  = 
              (format' (finishIndent ind) tn)
          prettyFormatTL' ind (tn:rtl) = 
              (format' ind                  tn) ++ (prettyFormatTL' ind rtl)

For comments code, the line length is up to 160 characters, at the maximum.

• Example:

  ------------------------------------------------------------------------------ |---...
   
  ...
  chSetInline :: [Char] -> Char -> Integer -> [Char]
  chSetInline [] chToSet nCol                                   -- there is no character at all
      | nCol > 0  = ' ' : (chSetInline ([]) chToSet (nCol-1))     -- -> extend with blank, recursively
      | nCol == 0 = chToSet : []                                  -- -> add character
      | otherwise = []                                            -- -> leave as is (empty)
  chSetInline lch0@(ch:lch) chToSet nCol                        -- there is at least one character
      | nCol > 0  = ch : (chSetInline lch chToSet (nCol-1))       -- -> go to next character, recursively
      | nCol == 0 = chToSet : lch                                 -- -> set character here
      | otherwise = lch0                                          -- -> leave as is

• four spaces
• no tabs

• lower camel case
• if the result has a dedicated type or is restricted to type class
  • then the first word (prefix) may suggest a type or type class
    • n for numbers
    • see also
      • Standard prefixes
      • Custom prefixes
  • continues with capital speaking names
    • e.g. Size, Replicate
    • Abbreviated names if to long
      • if available one of the suggested below
      • e.g. Pos for Position, Long for Longitude, In, Out
    • Combined as usually written
      • e.g. CursorPosition
    • If heavy abbreviation is needed without vowels
      • e.g. Cmp for Composition
• otherwise
  • the first word is a uncapitalized speaking name or a lower camel case of composed speaking names
• speaking names
  • noun (preferable to emphasise functional programming)
    • e.g. count/Count, matrix/Matrix, cursor/Cursor, length/Length
  • verbs
    • e.g. take/Take, replicate/Peplicate
• dependent on better readability abreviations within a name may be also written in camel case e.g. Sql for SQL, Ascii for ASCII
• examples:
  • takeEnd
  • niLength
  • length

Example outFromCmpOut with function name using custom prefix out to indicate the resulting custom type:

outFromCmpOut :: (ComposableOutput usrSym) -> (Output usrSym)

Example symTree as matched pattern name using custom prefix sym to indicate the custom type:

outFromCmpOut (CmpOut (CmpValid symTree _ _) _) = Valid symTree

Example lErr as matched name using standard prefix l plus err to indicate the custom list type combined with custom prefix err:

outFromCmpOut (CmpOut (CmpInvalid lerr) _) = Invalid lerr

• Prefixes for may be used types, type classes, and pattern

• Prefixes may be used for commonly used modules

• Prefixes for custom types, type classes, and pattern
  • custom prefixes are to be declared for each data type and type class
  • as in the example below
    • first bullet: * prefix: <prefix>
    • prefix in lower camel case

• -- EOLMode
  -- | ...EOL (end of line) mode.
  {-| 
  * prefix: eol
  ...
  -}
  data EOLMode = 
      ...

• example, in record syntax:

  • reolStream :: EOLMode, 

• -- Code
  -- | ...
  {-| 
  * prefix: cd
  ...
  -}
  class Code cd where 
      ...

• example, in a type constraint

  • fx :: Code cd => cd -> Char
    ...

• Prefixes for custom modules

• example:

  {-|
  Description : supports transformation from multiple system stream inputs like files and stdin to multiple system output stream like files, stdout and stderr.
  Copyright   : (c) Jörg K.-H. W. Brüggmann, 2021-2024
  License     : proprietary, to be dual licensed
  Maintainer  : info@joerg-brueggmann.de
  Stability   : experimental
  Portability : POSIX
   
  ...provides support for transformation from multiple system stream inputs like files and stdin to multiple system output stream like files, stdout and stderr.
   
    * suggested prefix: 'Mio'

• import qualified MultiOctetStreamIO as Mio

• Module description
• GHC extensions and options
• Module declaration and export list
  • keyword: module
• Sections
• Class declaration
  • keyword: class
• Data type declaration
  • keywords: data, type, newtype
• Instance declaration
  • keyword: instance
• Function declaration

• Haddock comment
• contains
  • description (Description)
    • in way that it becomes a complete sentence when started with module name
      • like in the code below it translates to HPowerLib.ExportTest makes it easier to export functional tests that are not exported themselves.
  • copyright according to the example below
  • license
    • All rights reserved
    • GPLv3+, see also file 'LICENSE' and 'README.md'
  • maintainer (Maintainer), always an email address
  • stability (Stability), possible values:
    • unstable
    • experimental
    • provisional
    • stable
    • frozen
  • portability (Portability), possible values:
    • portable
    • non-portable (<reason>)
  • bullets
    • most important properties
  • expandable example
    • may be with output of example
    • ideally using doc test
      • example:

        -- >>> fact 5
        -- 120 

• Example:

  {-|
  Description : makes it easier to export functional tests that are not exported themselves.
  Copyright   : (c) Jörg K.-H. W. Brüggmann, 2021-2024
  License     : All rights reserved
  Maintainer  : info@joerg-brueggmann.de
  Stability   : experimental
  Portability : POSIX
   
  * makes it easier to export functional tests that are not exported themselves.
   
  * suggested prefix: __/Exp/__
   
  * See also module HPowerLib.ImportTests, which supports import of the tests into the test framework Tasty.
   
  ==== __Example code to export tests__
   
   
      @
  ...
   
  module HPowerLib.Parser
      (
          ...
          , ...
          , testGroup_parseComposable
      ) where
   
  ...
      @
  -}

• after module documentation
• just listed one after the other
• only if needed

• Example:

  {-# LANGUAGE OverloadedStrings #-}
  {-# LANGUAGE GADTs #-}
  {-# LANGUAGE StandaloneDeriving #-}

• with export list
• each exported item classified according to sections

• Example:

  module HPowerLib.BitSeqContext
      (
          -- * data types and its instances
            Context( .. )
          , Position( .. )
          , LineNumber
          , ColumnNumber
          , BitPosition
          -- * functions regarding 'Context'
          , initFromOctets
          , initFromBits
          , startPositionMemory
          , position
          , isEOS
          -- * functions to test at context position
          -- ** class 'TestableEncoding' to test encodings
          , TestableEncoding( .. )
          -- * functions to test number of available bits
          , testAvailableBits
          -- * functions to test particular sequences
          , testCode
          , testBits
      ) where

• in order to get better overview
  • module's code is sectioned by comments, as shown below
  • two blank lines away from the text above
  • also to see whether the code is 80 character wide
• sections may separate
  • type class by type class
    • with its functions, if they can be associated
  • type by type
    • with its instances, if they are in the module, and can be associated
    • with its functions, if they can be associated

• example:

  --------------------------------------------------------------------------------
  --  data types and its instances
   
  data Context = Context { rBits :: Bits.Sequence, rPositionMemory :: ( Position, Maybe Char ) }
      deriving ( Eq, Show )
   
  ...
   
   
  --------------------------------------------------------------------------------
  --  functions regarding 'Context'
   
  initFromOctets :: Oct.Octets -> Context
  initFromOctets octets = Context ( Bits.Sequence Bits.NoSubOctet octets Bits.NoSubOctet ) startPositionMemory
   
  ...
   
   
  --------------------------------------------------------------------------------
  -- functions to test at context position
   
  --------------------------------------------------------------------------------
  -- class 'TestableEncoding' to test encodings
   
  class Cd.Code code => TestableEncoding code where
      decodeTest :: Context -> ( Maybe code, Context )
   
  instance TestableEncoding Cd.CharUtf8 where
      decodeTest :: Context -> (Maybe Cd.CharUtf8, Context)
      decodeTest context0@( Context _ pos0 ) =
  ...
   
  instance TestableEncoding Cd.CharIso1 where
      decodeTest context0 =
  ...
   
  instance TestableEncoding Cd.CharWin1 where
      decodeTest context0 =
  ...
   
  nextOctet :: Context -> ( Maybe Oct.Octet, Context )
  nextOctet context =
  ...
   
   
  --------------------------------------------------------------------------------
  -- functions to test number of available bits
   
  --------------------------------------------------------------------------------
  -- function 'testAvailableBits'
   
  testAvailableBits :: Context -> Integer -> ( Maybe Bits.Sequence, Context )
  testAvailableBits context0@( Context bits0 ( pos0, _ ) ) numberOfBits = 
  ...
   
   
  --------------------------------------------------------------------------------
  -- functions to test particular sequences
   
  --------------------------------------------------------------------------------
  -- function 'testCode'
   
  testCode :: Cd.Code cd => Context -> cd -> ( Bool, Context )
  testCode context code = ( contextBits == charBits, nextContext )
  ...
   
  nextCode :: Cd.Code cd => Context -> cd -> ( Bits.Sequence, Bits.Sequence, Context )
  nextCode ( Context bits pos ) code =
  ...
   
  nextPositionMemoryFromChar :: ( Position, Maybe Char ) -> Char -> Integer -> ( Position, Maybe Char )
  nextPositionMemoryFromChar ( BitPosition bitPosition0, _ ) _ nBits = ( BitPosition ( bitPosition0 + nBits ), Nothing )
  nextPositionMemoryFromChar ( CharAndBitPosition lineNumber0 columnNumber0 bitPosition0, mch0 ) ch nBits =
  ...
   
  --------------------------------------------------------------------------------
  -- function 'testBits'
   
  testBits :: Context -> Bits.Sequence -> ( Bool, Context )
  testBits context bitsToTest =
  ...

• example:

  -- HUnit
  -- | ...capability to compare the expected value with the actual one, 
  -- |    and to display the difference if there is one.
  {-| 
  -}
  class ( Show cmp ) => HUnit cmp where
      -- equals
      {- | ...compares the expected value with the actual one.
      * result 'True' if both values are equal, otherwise 'False'
      -}
      equals 
          :: cmp      -- ^ actual value
          -> cmp      -- ^ expected value
          -> Bool     -- ^ 'True' when actual value and expected value is considered equal, otherwise 'False'

• example:

  instance Format Prs.CharCode where
      display ( Prs.Utf8Code code ) = show ( Cd.chFromCode code ) ++ "(UTF-8)"
      display ( Prs.Iso1Code code ) = show ( Cd.chFromCode code ) ++ "(iso 8859-1)"
      display ( Prs.Win1Code code ) = show ( Cd.chFromCode code ) ++ "(Windows-1252)"

• it starts with the name in a single line comment, completed with …
• continues with multi line haddock comment
  • short description at the very top
  • blank line
  • bullets of properties, if neccessary

• example:

  -- EOLMode
  -- | ...EOL (end of line) mode.
  {-| 
  * prefix: eol
  * to determine row
  * to control generation of new lines
  -}
  data EOLMode = 
      -- | for Windows, a new line is "\r\n", and "\x0d\x0A", respectively
        WindowsEOL
      -- | for Unix, a new line is "\n", and "\x0A", respectively
      | UnixEOL
      -- for macOS, anew line is "\r", and "\x0d", respectively
      | MacEOL
      deriving Show

• example:

  -- Geoposition
  -- | ...geocoordinates in degrees.
  {-| 
  * prefix: gps
  -}
  data Geoposition = 
      Geoposition
          -- | Latitude
          Double
          -- | Longitude
          Double
      deriving Show

• example:

  -- | parser output that supports composition of all syntax elements including selections, sequences, repetitions, and so on
  data ComposableOutput =
      -- | previous input was valid or not yet parsed
        CmpValid
          -- | remaining input
          InputStream
          -- | symbol tree
          SymTree
          -- | lErrHintCmp
          [ErrorTree]
      -- | previous input was invalid
      | CmpInvalid
          -- | remaining input
          InputStream
          -- | error tree
          ErrorTree
      deriving Show

• indentation, line, comments and bracketing as in the example below
  • first line data <TypeName> =
  • second line <Constructor> {
  • haddock compliant comment, explaining the row below
  • record
    • bindings start with r to avoid shadowing when names are also used in pattern matching
    • the rest of the binding is as explained here

• -- Stream
  -- | ...string as input stream.
  {- |
  * prefix: st
  * that starts at column 1, row 1
  * going from left to right, and for each new line from top to bottom
  -}
  data Stream = 
      Stream {
          -- | controls the recognition of line breaks, which is important to calculate text positions ('Pos')
          reolStream :: EOLMode, 
          -- | keeps the rest of the stream if used by 'strFwdToNextChar'
          rsStream :: String, 
          -- | keeps the current position of the stream
          rposStream :: Pos }
      deriving Show

• example:

  someFunc :: IO ()
  someFunc = print crash
   
  data Unsafe = UnsafeA { rniA1 :: Int, rniA2 :: Int } | UnsafeB { rniB1 :: Int, rniB2 :: Int }
   
  unsafe = UnsafeB 23 34
   
  crash :: Int
  crash =  rniA1 unsafe

• output:

  XYZ-exe: No match in record selector rniA1

• example:

  someFunc :: IO ()
  someFunc = print cannotCrash
   
  data Safe = SafeA Int Int | SafeB Int Int
   
  safe = SafeB 23 34
   
  cannotCrash :: Int
  cannotCrash =  first safe
      where
          first :: Safe -> Int
          first (SafeA ni1 _) = ni1
          first (SafeB ni1 _) = ni1

• output:

  23

• function name and description should focus on what it provides, not what it does
  • e.g. “'Stream' that is initialised” instead of “initialises a 'Stream'”
• function name in single line comment, as idicated below
• Haddock comment
  • starts with what the function is doing
  • does not necessarily have to be a complete sentence
  • goes right into it
  • refers to the resulting type (in single quotes)
  • later bullets, after blank line, may indicate properties
• all rules for Binding names apply also to function name

• -- stInitalStream
  {-| ...'Stream' that is initialised.
  * from end of line mode ('EOLMode'), and content of the stream ('String')
  * resets posStream (:: Pos) to initial position
  -}
  stInitalStream
      :: EOLMode -- ^ end of line mode
      -> String  -- ^ content of the stream
      -> Stream  -- ^ the initialised stream
  stInitalStream eolMode s = Stream eolMode s initPos