Changes between Version 21 and Version 22 of Commentary/CodingStyle


Ignore:
Timestamp:
Apr 27, 2008 2:45:21 PM (7 years ago)
Author:
igloo
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/CodingStyle

    v21 v22  
    3030== To CPP or not to CPP? ==
    3131
    32 We pass all the compiler sources through CPP. The -cpp flag is always added by the build system.
     32Currently we pass all the compiler sources through CPP. The -cpp flag is always added by the build system.
     33However, whenever possible we try to avoid using CPP, as it can hide code from the compiler (which means changes that work on one platform can break the build on another) and code using CPP can be harder to understand.
     34
    3335The following CPP symbols are used throughout the compiler:
    3436
     
    3638  Used to enables extra checks and debugging output in the compiler. The ASSERT macro (see {{{HsVersions.h}}}) provides assertions which disappear when DEBUG is not defined.
    3739
    38  {{{HsVersions.h}}} provides a macro {{{debugIsOn}}} which is defined to be {{{True}}} when DEBUG is defined and {{{False}}} otherwise.  The ideal way to provide debugging output is to use a Haskell expression "{{{if debugIsOn then ... else ...}}}" to arrange that the compiler will be silent when DEBUG is off (unless of course something goes wrong or the verbosity level is nonzero).  The advantage of this scheme is that ''all code is typechecked on every compilation'', no matter what the setting of DEBUG.  When option {{{-O}}} is used, GHC will easily sweep away the unreachable code.
     40 However, whenever possible, it is better to us `debugIsOn` from the `Util` module, which is defined to be `True` when `DEBUG` is defined and `False` otherwise.  The ideal way to provide debugging output is to use a Haskell expression "`when debugIsOn $ ...`" to arrange that the compiler will be silent when `DEBUG` is off (unless of course something goes wrong or the verbosity level is nonzero). When option `-O` is used, GHC will easily sweep away the unreachable code.
    3941
    40  As a last resort, debugging code can be placed inside #ifdef DEBUG, but since this strategy guarantees that only a fraction of the code is seen be the compiler on any one compilation, it is to be avoided when possible.
     42 As a last resort, debugging code can be placed inside `#ifdef DEBUG`, but since this strategy guarantees that only a fraction of the code is seen be the compiler on any one compilation, it is to be avoided when possible.
    4143
    42  Regarding performance, a good rule of thumb is that DEBUG shouldn't add more than about 10-20% to the compilation time. This is the case at the moment. If it gets too expensive, we won't use it. For more expensive runtime checks, consider adding a flag - see for example -dcore-lint.
     44 Regarding performance, a good rule of thumb is that `DEBUG` shouldn't add more than about 10-20% to the compilation time. This is the case at the moment. If it gets too expensive, we won't use it. For more expensive runtime checks, consider adding a flag - see for example `-dcore-lint`.
    4345
    4446 '''GHCI'''::
     
    8688   everything should compile with the NCG nowadays, but that wasn't always the case).
    8789
    88 Don't bother putting -cpp or -fglasgow-exts in the OPTIONS pragma; these are already added to the command line by the build system.
     90Don't bother putting `-cpp` or `-fglasgow-exts` in the `OPTIONS` pragma; these are already added to the command line by the build system.
    8991
    9092=== Exports ===
     
    130132}}}
    131133
    132 Import library modules from the core packages only (core packages are listed in [[GhcFile(libraries/core-packages)]]). Use `#defines `in `HsVersions.h` when the modules names differ between versions of GHC.  For code inside `#ifdef GHCI`, don't worry about GHC versioning issues, because this code is only ever compiled by the this very version of GHC.
     134Import library modules from the boot packages only (boot packages are listed in [[GhcFile(libraries/boot-packages)]]). Use `#defines `in `HsVersions.h` when the modules names differ between versions of GHC.  For code inside `#ifdef GHCI`, don't worry about GHC versioning issues, because this code is only ever compiled by the this very version of GHC.
    133135
    134136'''Do not use explicit import lists''', except to resolve name clashes.  There are several reasons for this:
     
    153155
    154156Often it's better to write out the code longhand than to reuse a generic abstraction (not always, of course).  Sometimes it's better to duplicate some similar code than to try to construct an elaborate generalisation with only two instances.  Remember: other people have to be able to quickly understand what you've done, and overuse of abstractions just serves to obscure the ''really'' tricky stuff, and there's no shortage of that in GHC.
    155