Changes between Version 2 and Version 3 of Commentary/CodingStyle


Ignore:
Timestamp:
Oct 10, 2006 1:25:15 PM (8 years ago)
Author:
simonmar
Comment:

change policy on import declarations

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/CodingStyle

    v2 v3  
    9797-- GHC 
    9898import CoreSyn 
    99 import Id           ( idName, idType ) 
     99import Id 
    100100import BasicTypes 
    101101 
    102102-- libraries 
    103 import DATA_IOREF   ( newIORef, readIORef ) 
     103import Data.IORef 
    104104 
    105105-- std 
    106 import List         ( partition ) 
    107 import Maybe        ( fromJust ) 
     106import Data.List 
     107import Data.Maybe 
    108108}}} 
    109109 
    110 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).  
     110Import 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. 
    111111 
    112 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.  
     112'''Do not use explicit import lists''', except to resolve name clashes.  There are several reasons for this: 
    113113 
    114 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.  
     114 * They slow down development: almost every change is accompanied by an import list change. 
    115115 
    116 ToDo: finish this  
     116 * They cause spurious conflicts between developers. 
     117 
     118 * They lead to useless warnings about unused imports, and time wasted trying to 
     119   keep the import declarations "minimal". 
     120 
     121 * GHC's warnings are useful for detecting unnecessary imports: see `-fwarn-unused-imports`. 
     122 
     123 * TAGS is a good way to find out where an identifier is defined (use `make tags` in `ghc/compiler`, 
     124   and hit `M-.` in emacs). 
     125 
     126If 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.  
     127 
     128 
     129=== General Style === 
     130 
     131It's much better to write code that is transparent, than to write code that is short. 
     132 
     133Often 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. 
     134