The GHC Commentary - Coding Style Guidelines

From ef87e1378095a6e4831a207b5333f02f7c24283d Mon Sep 17 00:00:00 2001 From: simonmar Date: Wed, 28 Aug 2002 16:02:52 +0000 Subject: [PATCH] [project @ 2002-08-28 16:02:51 by simonmar] Add the beginnings of the "Coding Style Guidelines" for ghc/compiler. --- ghc/docs/comm/index.html | 2 + ghc/docs/comm/the-beast/coding-style.html | 152 +++++++++++++++++++++++++++++ 2 files changed, 154 insertions(+) create mode 100644 ghc/docs/comm/the-beast/coding-style.html diff --git a/ghc/docs/comm/index.html b/ghc/docs/comm/index.html index b88c15e..224fb11 100644 --- a/ghc/docs/comm/index.html +++ b/ghc/docs/comm/index.html @@ -52,6 +52,8 @@

The Beast Dissected

Coding style used in + the compiler
The Glorious Driver
Primitives and the Prelude
Just Syntax diff --git a/ghc/docs/comm/the-beast/coding-style.html b/ghc/docs/comm/the-beast/coding-style.html new file mode 100644 index 0000000..7f0efbf --- /dev/null +++ b/ghc/docs/comm/the-beast/coding-style.html @@ -0,0 +1,152 @@ + + + + + The GHC Commentary - Coding Style Guidelines + + + +
The GHC Commentary - Coding Style Guidelines
+ +
This is a rough description of some of the coding practices and + style that we use for Haskell code inside ghc/compiler. + +
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. + +
To literate or not to literate?
+ +
In GHC we use a mixture of literate (.lhs) and + non-literate (.hs) source. I (Simon M.) prefer to use + non-literate style, because I think the + \begin{code}..\end{code} 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). + +
To CPP or not to CPP?
+ +
We pass all the compiler sources through CPP. The + -cpp flag is always added by the build system. More + about what you're allowed to do in the way of CPP directives + later. + +
Compiler versions
+ +
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. + +
To maintain compatibility, use HsVersions.h (see + below) where possible, and try to avoid using #ifdef in + the source itself. + +
The source file
+ +
We now describe a typical source file, annotating stylistic + choices as we go. + +
```
+{-# OPTIONS ... #-}
+
```
+ +
An OPTIONS pragma is optional, but if present it + should go right at the top of the file. Things you might want to + put in OPTIONS include: + +
- -#include options to bring into scope prototypes + for FFI declarations
- -fvia-C if you know that + this module won't compile with the native code generator. +
+ +
Don't bother putting -cpp or -fglasgow-exts + in the OPTIONS pragma; these are already added to the + command line by the build system. + + +
```
+module Foo (
+   T(..),
+   foo,	     -- :: T -> T
+ ) where
+
```
+ +
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. + +
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. + +
```
+#include "HsVersions.h"
+
```
+ +
HsVersions.h 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. + +
```
+-- 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 )
+
```
+ +
List imports in the following order: + +
- Local to this subsystem (or directory) first
- Compiler imports, generally ordered from specific to generic + (ie. modules from utils/ and basicTypes/ + usually come last)
- Library imports
- Standard Haskell 98 imports last
+ +
Import library modules from the base and + haskell98 packages only. Use #defines in + HsVersions.h when the modules names differ between + versions of GHC (eg. DATA_IOREF in the example above). + For code inside #ifdef GHCI, don't need to worry about GHC + versioning (because we are bootstrapped). + +
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 -fwarn-unused-imports + flag so that you get notified when an import isn't being used any + more. + +
If the module can be compiled multiple ways (eg. GHCI + vs. non-GHCI), make sure the imports are properly #ifdefed + too, so as to avoid spurious unused import warnings. + +
ToDo: finish this + + -- 1.7.10.4

The Beast Dissected

The GHC Commentary - Coding Style Guidelines

To literate or not to literate?

To CPP or not to CPP?

Compiler versions

The source file