Changes between Version 42 and Version 43 of Development/CodeConventions


Ignore:
Timestamp:
Jul 18, 2014, 3:39:04 AM (3 years ago)
Author:
benl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v42 v43  
    1111 * Each top-level definition should have a comment explaining what it is for. One liners are fine.
    1212
    13  * Running comments in the bodies of functions are encouraged. Write down what you were expecting the code to do when you wrote it, so it reads like a story. Aim for 1 comment line at least every 5-10 code lines, depending on how complex the code is. This level of commenting would be overkill for a cookie-cutter program like a database GUI, but compilers are a completely different beast. See the [http://code.ouroborus.net/ddc/ddc-head/packages/ddc-core/DDC/Core/Check/CheckExp.hs CheckExp]  module in the type checker for a good example.
     13 * Running comments in the bodies of functions are encouraged. Write down what you were expecting the code to do when you wrote it, so it reads like a story. Aim for 1 comment line at least every 5-10 code lines, depending on how complex the code is. This level of commenting would be overkill for a cookie-cutter program like a database GUI, but compilers are a completely different beast. See the [https://github.com/DDCSF/ddc/blob/ddc-0.4.1/packages/ddc-core/DDC/Core/Check/Judge/Type/AppX.hs AppX]  module in the type checker for a good example.
    1414
    1515 * All top-level bindings should have a type signature. Exceptions can be made for functions that are continuations of others, as they will never need to be called from outside the module they are defined in.