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.