Changes between Version 48 and Version 49 of Commentary/CodingStyle


Ignore:
Timestamp:
Jul 15, 2014 9:58:54 PM (13 months ago)
Author:
simonpj
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/CodingStyle

    v48 v49  
    3030We use Haddock so that the comment is included in the generated HTML documentation.
    3131
    32 === Comments and commit messages ===
     32=== Comments in the source code ===
    3333
    3434Commenting is good but
     
    7272Please use this technique.  It's robust, and survives successive changes to the same lines of code.  When you are changing code, it draws attention to non-obvious things you might want to bear in mind.  When you encounter the note itself you can search for the string to find the code that implements the thoughts contained in the comment.
    7373
    74 Please do not put comments like these in commit messages instead, ''even if the patch is devoted to a single change''.  The information is harder to find in a commit message, and (much worse) there is no explicit indication in the code that there is carefully-written information available about that particular line of code.  Instead, you can refer to the Note from the commit message.
    75 
    76 (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".)
    77 
    7874=== Comments and examples ===
    7975
     
    105101Comments 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.
    106102
     103=== Commit messages ===
     104
     105Please use commit messages to describe how something works, or give examples, ''even if the patch is devoted to a single change''.  The information is harder to find in a commit message, and (much worse) there is no explicit indication in the code that there is carefully-written information available about that particular line of code.  Instead, you can refer to the Note from the commit message.
     106
     107Commit 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". 
     108They are also a useful place to say which ticket is fixed by the commit, summarise the changes embodied in the commit etc. 
     109
     110In short, commit messages describe ''changes'', whereas comment explain the code ''as it now is''.
     111
    107112== Warnings ==
    108113