Changes between Version 24 and Version 25 of Commentary/CodingStyle


Ignore:
Timestamp:
May 2, 2008 7:16:18 PM (6 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 ==