ghc/docs/comm/the-beast/coding-style.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
   5     <title>The GHC Commentary - Coding Style Guidelines</title>
   6   </head>
   7
   8   <body BGCOLOR="FFFFFF">
   9     <h1>The GHC Commentary - Coding Style Guidelines</h1>
  10
  11     <p>This is a rough description of some of the coding practices and
  12     style that we use for Haskell code inside <tt>ghc/compiler</tt>.
  13
  14     <p>The general rule is to stick to the same coding style as is
  15     already used in the file you're editing.  If you must make
  16     stylistic changes, commit them separately from functional changes,
  17     so that someone looking back through the change logs can easily
  18     distinguish them.
  19
  20     <h2>To literate or not to literate?</h2>
  21
  22     <p>In GHC we use a mixture of literate (<tt>.lhs</tt>) and
  23     non-literate (<tt>.hs</tt>) source.  I (Simon M.) prefer to use
  24     non-literate style, because I think the
  25     <tt>\begin{code}..\end{code}</tt> clutter up the source too much,
  26     and I like to use Haddock-style comments (we haven't tried
  27     processing the whole of GHC with Haddock yet, though).
  28
  29     <h2>To CPP or not to CPP?</h2>
  30
  31     <p>We pass all the compiler sources through CPP.  The
  32     <tt>-cpp</tt> flag is always added by the build system.  More
  33     about what you're allowed to do in the way of CPP directives
  34     later.
  35
  36     <h2>Compiler versions</h2>
  37
  38     <p>GHC must be compilable by every major version of GHC from 4.08
  39     onwards, and itself.  It isn't necessary for it to be compilable
  40     by every intermediate development version (that includes last
  41     week's CVS sources), but we mustn't lose compatibility with 4.08
  42     for the time being, because that's the only version which can be
  43     easily bootstrapped from .hc files.
  44
  45     <p>To maintain compatibility, use <tt>HsVersions.h</tt> (see
  46     below) where possible, and try to avoid using <tt>#ifdef</tt> in
  47     the source itself.
  48
  49     <h2>The source file</h2>
  50
  51     <p>We now describe a typical source file, annotating stylistic
  52     choices as we go.
  53
  54 <pre>
  55 {-# OPTIONS ... #-}
  56 </pre>
  57
  58     <p>An <tt>OPTIONS</tt> pragma is optional, but if present it
  59     should go right at the top of the file.  Things you might want to
  60     put in <tt>OPTIONS</tt> include:
  61
  62     <ul>
  63       <li><tt>-#include</tt> options to bring into scope prototypes
  64       for FFI declarations</li>
  65       <li><tt>-fvia-C</tt> if you know that
  66       this module won't compile with the native code generator.
  67     </ul>
  68
  69     <p>Don't bother putting <tt>-cpp</tt> or <tt>-fglasgow-exts</tt>
  70     in the <tt>OPTIONS</tt> pragma; these are already added to the
  71     command line by the build system.
  72
  73
  74 <pre>
  75 module Foo (
  76    T(..),
  77    foo,      -- :: T -> T
  78  ) where
  79 </pre>
  80
  81     <p>We usually (99% of the time) include an export list.  The only
  82     exceptions are perhaps where the export list would list absolutely
  83     everything in the module, and even then sometimes we do it anyway.
  84
  85     <p>It's helpful to give type signatures inside comments in the
  86     export list, but hard to keep them consistent, so we don't always
  87     do that.
  88
  89 <pre>
  90 #include "HsVersions.h"
  91 </pre>
  92
  93     <p><tt>HsVersions.h</tt> is a CPP header file containing a number
  94     of macros that help smooth out the differences between compiler
  95     versions.  It defines, for example, macros for library module
  96     names which have moved between versions.  Take a look.
  97
  98 <pre>
  99 -- friends
 100 import SimplMonad
 101
 102 -- GHC
 103 import CoreSyn
 104 import Id           ( idName, idType )
 105 import BasicTypes
 106
 107 -- libraries
 108 import DATA_IOREF   ( newIORef, readIORef )
 109
 110 -- std
 111 import List         ( partition )
 112 import Maybe        ( fromJust )
 113 </pre>
 114
 115    <p>List imports in the following order:
 116
 117    <ul>
 118      <li>Local to this subsystem (or directory) first</li>
 119
 120      <li>Compiler imports, generally ordered from specific to generic
 121        (ie. modules from <tt>utils/</tt> and <tt>basicTypes/</tt>
 122        usually come last)</li>
 123
 124      <li>Library imports</li>
 125
 126      <li>Standard Haskell 98 imports last</li>
 127    </ul>
 128
 129    <p>Import library modules from the <tt>base</tt> and
 130    <tt>haskell98</tt> packages only.  Use <tt>#defines</tt> in
 131    <tt>HsVersions.h</tt> when the modules names differ between
 132    versions of GHC (eg. <tt>DATA_IOREF</tt> in the example above).
 133    For code inside <tt>#ifdef GHCI</tt>, don't need to worry about GHC
 134    versioning (because we are bootstrapped).
 135
 136    <p>We usually use import specs to give an explicit list of the
 137    entities imported from a module.  The main reason for doing this is
 138    so that you can search the file for an entity and find which module
 139    it comes from.  However, huge import lists can be a pain to
 140    maintain, so we often omit the import specs when they start to get
 141    long (actually I start omitting them when they don't fit on one
 142    line --Simon M.).  Tip: use GHC's <tt>-fwarn-unused-imports</tt>
 143    flag so that you get notified when an import isn't being used any
 144    more.
 145
 146    <p>If the module can be compiled multiple ways (eg. GHCI
 147    vs. non-GHCI), make sure the imports are properly <tt>#ifdefed</tt>
 148    too, so as to avoid spurious unused import warnings.
 149
 150    <p><em>ToDo: finish this</em>
 151   </body>
 152 </html>