Changes between Version 35 and Version 36 of Development/CodeConventions


Ignore:
Timestamp:
Dec 5, 2012, 12:24:50 PM (7 years ago)
Author:
benl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v35 v36  
    99
    1010=== Comments ===
    11  * If you can't work something out then open a ticket on the trac and set the ticket type to `document`. If you tried to understand something but failed to do so in a reasonable timeframe, then this is a bug against the maintainability of the software. Don't assume that the next person that looks at the same code will be able to make more sense of it than you could.
     11 * '''Critital:''' If you tried to understand something but gave up before doing so then open a ticket on the trac and set the ticket type to `document`. This is a bug against the maintainability of the software. Don't assume that the next person that looks at the same code will be able to make more sense of it than you could, or have more patience.
    1212
    1313 * Each top-level definition should have a comment explaining what it is for. One liners are fine.
    1414
    15  * 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.
     15 * 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.
    1616
    1717 * 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.
     
    158158
    159159Using a "where" is ok when baz does something trivial, like initialise a loop. However, any time "baz" does something interesting you should use a let, otherwise the conceptual flow of the code is ruined. Using let over where also makes it easier to convert to strict Disciple code.
    160