1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
4 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
5 <title>The GHC Commentary - Coding Style Guidelines</title>
8 <body BGCOLOR="FFFFFF">
9 <h1>The GHC Commentary - Coding Style Guidelines</h1>
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>.
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
20 <h2>To literate or not to literate?</h2>
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).
29 <h2>To CPP or not to CPP?</h2>
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
36 <h2>Compiler versions</h2>
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.
45 <p>To maintain compatibility, use <tt>HsVersions.h</tt> (see
46 below) where possible, and try to avoid using <tt>#ifdef</tt> in
49 <h2>The source file</h2>
51 <p>We now describe a typical source file, annotating stylistic
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:
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.
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.
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.
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
90 #include "HsVersions.h"
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.
104 import Id ( idName, idType )
108 import DATA_IOREF ( newIORef, readIORef )
111 import List ( partition )
112 import Maybe ( fromJust )
115 <p>List imports in the following order:
118 <li>Local to this subsystem (or directory) first</li>
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>
124 <li>Library imports</li>
126 <li>Standard Haskell 98 imports last</li>
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).
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
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.
150 <p><em>ToDo: finish this</em>