--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <title>The GHC Commentary - Coding Style Guidelines</title>
+ </head>
+
+ <body BGCOLOR="FFFFFF">
+ <h1>The GHC Commentary - Coding Style Guidelines</h1>
+
+ <p>This is a rough description of some of the coding practices and
+ style that we use for Haskell code inside <tt>ghc/compiler</tt>.
+
+ <p>The general rule is to stick to the same coding style as is
+ already used in the file you're editing. If you must make
+ stylistic changes, commit them separately from functional changes,
+ so that someone looking back through the change logs can easily
+ distinguish them.
+
+ <h2>To literate or not to literate?</h2>
+
+ <p>In GHC we use a mixture of literate (<tt>.lhs</tt>) and
+ non-literate (<tt>.hs</tt>) source. I (Simon M.) prefer to use
+ non-literate style, because I think the
+ <tt>\begin{code}..\end{code}</tt> clutter up the source too much,
+ and I like to use Haddock-style comments (we haven't tried
+ processing the whole of GHC with Haddock yet, though).
+
+ <h2>To CPP or not to CPP?</h2>
+
+ <p>We pass all the compiler sources through CPP. The
+ <tt>-cpp</tt> flag is always added by the build system. More
+ about what you're allowed to do in the way of CPP directives
+ later.
+
+ <h2>Compiler versions</h2>
+
+ <p>GHC must be compilable by every major version of GHC from 4.08
+ onwards, and itself. It isn't necessary for it to be compilable
+ by every intermediate development version (that includes last
+ week's CVS sources), but we mustn't lose compatibility with 4.08
+ for the time being, because that's the only version which can be
+ easily bootstrapped from .hc files.
+
+ <p>To maintain compatibility, use <tt>HsVersions.h</tt> (see
+ below) where possible, and try to avoid using <tt>#ifdef</tt> in
+ the source itself.
+
+ <h2>The source file</h2>
+
+ <p>We now describe a typical source file, annotating stylistic
+ choices as we go.
+
+<pre>
+{-# OPTIONS ... #-}
+</pre>
+
+ <p>An <tt>OPTIONS</tt> pragma is optional, but if present it
+ should go right at the top of the file. Things you might want to
+ put in <tt>OPTIONS</tt> include:
+
+ <ul>
+ <li><tt>-#include</tt> options to bring into scope prototypes
+ for FFI declarations</li>
+ <li><tt>-fvia-C</tt> if you know that
+ this module won't compile with the native code generator.
+ </ul>
+
+ <p>Don't bother putting <tt>-cpp</tt> or <tt>-fglasgow-exts</tt>
+ in the <tt>OPTIONS</tt> pragma; these are already added to the
+ command line by the build system.
+
+
+<pre>
+module Foo (
+ T(..),
+ foo, -- :: T -> T
+ ) where
+</pre>
+
+ <p>We usually (99% of the time) include an export list. The only
+ exceptions are perhaps where the export list would list absolutely
+ everything in the module, and even then sometimes we do it anyway.
+
+ <p>It's helpful to give type signatures inside comments in the
+ export list, but hard to keep them consistent, so we don't always
+ do that.
+
+<pre>
+#include "HsVersions.h"
+</pre>
+
+ <p><tt>HsVersions.h</tt> is a CPP header file containing a number
+ of macros that help smooth out the differences between compiler
+ versions. It defines, for example, macros for library module
+ names which have moved between versions. Take a look.
+
+<pre>
+-- friends
+import SimplMonad
+
+-- GHC
+import CoreSyn
+import Id ( idName, idType )
+import BasicTypes
+
+-- libraries
+import DATA_IOREF ( newIORef, readIORef )
+
+-- std
+import List ( partition )
+import Maybe ( fromJust )
+</pre>
+
+ <p>List imports in the following order:
+
+ <ul>
+ <li>Local to this subsystem (or directory) first</li>
+
+ <li>Compiler imports, generally ordered from specific to generic
+ (ie. modules from <tt>utils/</tt> and <tt>basicTypes/</tt>
+ usually come last)</li>
+
+ <li>Library imports</li>
+
+ <li>Standard Haskell 98 imports last</li>
+ </ul>
+
+ <p>Import library modules from the <tt>base</tt> and
+ <tt>haskell98</tt> packages only. Use <tt>#defines</tt> in
+ <tt>HsVersions.h</tt> when the modules names differ between
+ versions of GHC (eg. <tt>DATA_IOREF</tt> in the example above).
+ For code inside <tt>#ifdef GHCI</tt>, don't need to worry about GHC
+ versioning (because we are bootstrapped).
+
+ <p>We usually use import specs to give an explicit list of the
+ entities imported from a module. The main reason for doing this is
+ so that you can search the file for an entity and find which module
+ it comes from. However, huge import lists can be a pain to
+ maintain, so we often omit the import specs when they start to get
+ long (actually I start omitting them when they don't fit on one
+ line --Simon M.). Tip: use GHC's <tt>-fwarn-unused-imports</tt>
+ flag so that you get notified when an import isn't being used any
+ more.
+
+ <p>If the module can be compiled multiple ways (eg. GHCI
+ vs. non-GHCI), make sure the imports are properly <tt>#ifdefed</tt>
+ too, so as to avoid spurious unused import warnings.
+
+ <p><em>ToDo: finish this</em>
+ </body>
+</html>
projects / ghc-hetmet.git / commitdiff