Legend:

* 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.

12

12

13

13

* Each top-level definition should have a comment explaining what it is for. One liners are fine.

14

14

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.

16

16

17

17

* 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.

Using 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.