Changes between Version 31 and Version 32 of Development/CodeConventions


Ignore:
Timestamp:
Dec 2, 2012, 11:55:07 AM (6 years ago)
Author:
benl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v31 v32  
    1717 * Each top-level definition should have a comment explaining what it is for. One liners are fine.
    1818
    19  * 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 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. For `n` lines of code there are potentially `n^2` bugs (at least), so we want to know exactly what each line is trying to achieve.
     19 * 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 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.
    2020
    2121 * 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.
     
    156156
    157157
    158