Changes between Version 32 and Version 33 of Commentary/CodingStyle


Ignore:
Timestamp:
Apr 24, 2011 10:00:50 PM (4 years ago)
Author:
megacz
Comment:

try to improve section structuring

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/CodingStyle

    v32 v33  
    88The 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.  
    99 
    10 == Comments and commit messages == 
     10== Comments == 
     11=== Comments and commit messages === 
    1112 
    1213Commenting is good but 
     
    5455(Commit messages can nevertheless contain substantial information, but it is usually of a global nature.  E.g. "This patch modifies 20 files to implement a new form of inlining pragma".) 
    5556 
    56 == Comments and examples == 
     57=== Comments and examples === 
    5758 
    5859When writing a comment to explain a subtle point, consider including an example code 
     
    7980 * Cite a test case in the test suite that illustrates it 
    8081 
    81 == Longer comments or architectural commentary == 
     82=== Longer comments or architectural commentary === 
    8283 
    8384Comments with a broad scope, describing the architecture or workings of more than one module, belong here in the commentary rather than in the code.  Put the URL for the relevant commentary page in a comment in the code itself, and also put URLs for all relevant commentary pages in a comment at the top of each module. 
     
    99100pragma; you are encouraged to remove this pragma and fix any warnings when working on a module. 
    100101 
    101 == To literate or not to literate? == 
     102== Literate Haskell == 
    102103 
    103104In 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).  
    104105 
    105 == To CPP or not to CPP? == 
     106== The C Preprocessor (CPP) == 
    106107 
    107108Currently we pass all the compiler sources through CPP. The -cpp flag is always added by the build system.  
     
    139140Also, it is necessary to avoid certain language extensions.  In particular, the {{{ScopedTypeVariables}}} extension must not be used. 
    140141 
    141 == The source file == 
     142== Walk-through of a sample source file == 
    142143 
    143144We now describe a typical source file, annotating stylistic choices as we go.