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.
  33
  34     <p>The following CPP symbols are used throughout the compiler:
  35
  36     <dl>
  37       <dt><tt>DEBUG</tt></dt>
  38
  39       <dd>Used to enables extra checks and debugging output in the
  40       compiler.  The <tt>ASSERT</tt> macro (see <tt>HsVersions.h</tt>)
  41       provides assertions which disappear when <tt>DEBUG</tt> is not
  42       defined.
  43
  44       <p>All debugging output should be placed inside <tt>#ifdef
  45       DEBUG</tt>; we generally use this to provide warnings about
  46       strange cases and things that might warrant investigation.  When
  47       <tt>DEBUG</tt> is off, the compiler should normally be silent
  48       unless something goes wrong (exception when the verbosity level
  49       is greater than zero).
  50
  51       <p>A good rule of thumb is that <tt>DEBUG</tt> shouldn't add
  52       more than about 10-20% to the compilation time.  This is the case
  53       at the moment.  If it gets too expensive, we won't use it.  For
  54       more expensive runtime checks, consider adding a flag - see for
  55       example <tt>-dcore-lint</tt>.
  56       </dd>
  57
  58       <dt><tt>GHCI</tt></dt>
  59
  60       <dd>Enables GHCi support, including the byte code generator and
  61       interactive user interface.  This isn't the default, because the
  62       compiler needs to be bootstrapped with itself in order for GHCi
  63       to work properly.  The reason is that the byte-code compiler and
  64       linker are quite closely tied to the runtime system, so it is
  65       essential that GHCi is linked with the most up-to-date RTS.
  66       Another reason is that the representation of certain datatypes
  67       must be consistent between GHCi and its libraries, and if these
  68       were inconsistent then disaster could follow.
  69       </dd>
  70
  71     </dl>
  72
  73     <p>More about what you're allowed to do in the way of CPP
  74     directives later.
  75
  76     <h2>Compiler versions</h2>
  77
  78     <p>GHC must be compilable by every major version of GHC from 4.08
  79     onwards, and itself.  It isn't necessary for it to be compilable
  80     by every intermediate development version (that includes last
  81     week's CVS sources), but we mustn't lose compatibility with 4.08
  82     for the time being, because that's the only version which can be
  83     easily bootstrapped from .hc files.
  84
  85     <p>To maintain compatibility, use <tt>HsVersions.h</tt> (see
  86     below) where possible, and try to avoid using <tt>#ifdef</tt> in
  87     the source itself.
  88
  89     <h2>The source file</h2>
  90
  91     <p>We now describe a typical source file, annotating stylistic
  92     choices as we go.
  93
  94 <pre>
  95 {-# OPTIONS ... #-}
  96 </pre>
  97
  98     <p>An <tt>OPTIONS</tt> pragma is optional, but if present it
  99     should go right at the top of the file.  Things you might want to
 100     put in <tt>OPTIONS</tt> include:
 101
 102     <ul>
 103       <li><tt>-#include</tt> options to bring into scope prototypes
 104       for FFI declarations</li>
 105       <li><tt>-fvia-C</tt> if you know that
 106       this module won't compile with the native code generator.
 107     </ul>
 108
 109     <p>Don't bother putting <tt>-cpp</tt> or <tt>-fglasgow-exts</tt>
 110     in the <tt>OPTIONS</tt> pragma; these are already added to the
 111     command line by the build system.
 112
 113
 114 <pre>
 115 module Foo (
 116    T(..),
 117    foo,      -- :: T -> T
 118  ) where
 119 </pre>
 120
 121     <p>We usually (99% of the time) include an export list.  The only
 122     exceptions are perhaps where the export list would list absolutely
 123     everything in the module, and even then sometimes we do it anyway.
 124
 125     <p>It's helpful to give type signatures inside comments in the
 126     export list, but hard to keep them consistent, so we don't always
 127     do that.
 128
 129 <pre>
 130 #include "HsVersions.h"
 131 </pre>
 132
 133     <p><tt>HsVersions.h</tt> is a CPP header file containing a number
 134     of macros that help smooth out the differences between compiler
 135     versions.  It defines, for example, macros for library module
 136     names which have moved between versions.  Take a look.
 137
 138 <pre>
 139 -- friends
 140 import SimplMonad
 141
 142 -- GHC
 143 import CoreSyn
 144 import Id           ( idName, idType )
 145 import BasicTypes
 146
 147 -- libraries
 148 import DATA_IOREF   ( newIORef, readIORef )
 149
 150 -- std
 151 import List         ( partition )
 152 import Maybe        ( fromJust )
 153 </pre>
 154
 155    <p>List imports in the following order:
 156
 157    <ul>
 158      <li>Local to this subsystem (or directory) first</li>
 159
 160      <li>Compiler imports, generally ordered from specific to generic
 161        (ie. modules from <tt>utils/</tt> and <tt>basicTypes/</tt>
 162        usually come last)</li>
 163
 164      <li>Library imports</li>
 165
 166      <li>Standard Haskell 98 imports last</li>
 167    </ul>
 168
 169    <p>Import library modules from the <tt>base</tt> and
 170    <tt>haskell98</tt> packages only.  Use <tt>#defines</tt> in
 171    <tt>HsVersions.h</tt> when the modules names differ between
 172    versions of GHC (eg. <tt>DATA_IOREF</tt> in the example above).
 173    For code inside <tt>#ifdef GHCI</tt>, don't need to worry about GHC
 174    versioning (because we are bootstrapped).
 175
 176    <p>We usually use import specs to give an explicit list of the
 177    entities imported from a module.  The main reason for doing this is
 178    so that you can search the file for an entity and find which module
 179    it comes from.  However, huge import lists can be a pain to
 180    maintain, so we often omit the import specs when they start to get
 181    long (actually I start omitting them when they don't fit on one
 182    line --Simon M.).  Tip: use GHC's <tt>-fwarn-unused-imports</tt>
 183    flag so that you get notified when an import isn't being used any
 184    more.
 185
 186    <p>If the module can be compiled multiple ways (eg. GHCI
 187    vs. non-GHCI), make sure the imports are properly <tt>#ifdefed</tt>
 188    too, so as to avoid spurious unused import warnings.
 189
 190    <p><em>ToDo: finish this</em>
 191   </body>
 192 </html>