Changes between Version 24 and Version 25 of Commentary/CodingStyle


Ignore:
Timestamp:
May 2, 2008 7:16:18 PM (7 years ago)
Author:
simonpj
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/CodingStyle

    v24 v25  
    3535There's a chance that e will be a constructor application or function, or something
    3636like that, so moving the coerion to the usage site may well cancel the coersions
    37 and lead to further optimisation.  Example:
     37and lead to further optimisation. 
    3838        ...more stuff about coercion floating...
    3939-}
     
    5353
    5454(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".)
     55
     56== Comments and examples ==
     57
     58When writing a comment to explain a subtle point, consider including an example code
     59snippet that illustrates the point.  For example, the above `Note [Float coercions]` contines thus:
     60{{{
     61There's a chance that e will be a constructor application or function, or something
     62like that, so moving the coerion to the usage site may well cancel the coersions
     63and lead to further optimisation.  Example:
     64
     65     data family T a :: *
     66     data instance T Int = T Int
     67
     68     foo :: Int -> Int -> Int
     69     foo m n = ...
     70        where
     71          x = T m
     72          go 0 = 0
     73          go n = case x of { T m -> go (n-m) }
     74                -- This case should optimise
     75}}}
     76These kind of code snippets are extremely helpful to illustrate the point in a
     77concrete way.  Other ways of making the comment concrete are:
     78 * Cite a particular Trac ticket that this bit of code deals with
     79 * Cite a test case in the test suite that illustrates it
    5580
    5681== Warnings ==