Changes between Version 38 and Version 39 of Development/CodeConventions


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

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v38 v39  
    44The golden rule is to follow whatever conventions are already being used in the module you're editing. If you're creating a new module then follow the conventions used in existing modules.
    55
    6 If you're not sure what the conventions are, then ask. If you can think of a better way of doing it then let us know on the mailing list. This goes for development process and the use of library functions, as much as formatting and commenting style. The DDC project was started some time ago, and times change...
     6If you're not sure what the conventions are, then ask. If you can think of a better way of doing it then let us know on the mailing list. This goes for development process and the use of library functions, as much as formatting and commenting style. The DDC project was started years ago, and times change...
    77
    88== Comments ==
    9  * '''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.
     9 * '''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.
    1010
    1111 * Each top-level definition should have a comment explaining what it is for. One liners are fine.
     
    1313 * 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.
    1414
    15  * 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.
     15 * 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. If you have more than a few dividers in a module then consider breaking it up into smaller modules.
    1616
    1717 * Feel free to add dividers like:
     
    2020 }}}
    2121
    22  Such dividers increase the structure of the code and help the reader find things, especially with syntax highlighting editors. Most dividers should be 100, 80 or 40 chars wide. Most code should fit in 80 columns, but it's ok to use 100 if needed. If you have more than a few dividers in a module then consider breaking it up into smaller modules.
    23 
     22 Such dividers increase the structure of the code and help the reader find things, especially with syntax highlighting editors. Most dividers should be 100, 80 or 40 chars wide.
    2423
    2524== Spacing ==
     
    2827 * Corollary to the above: don't use tabs. Keep your editor set to 'soft-tabs' mode so that when you press the tab key it inserts 8 spaces.
    2928
     29* Most code should fit in 80 columns, but it's ok to use up to 100 if needed. Don't go over 100 columns.
    3030
    3131== Layout ==
    32  * We try to avoid having multiple  competing layout styles in DDC. Having different styles creates "accidental complexity", that is, syntactic differences in the source that don't equate to real functional differences. If we change styles then they should be documented so the we can migrate the code base towards using them.
     32 * We try to avoid having multiple layout styles in DDC. Having different styles creates "accidental complexity", that is, syntactic differences in the source that don't equate to real functional differences. If we change layout style then this should be documented here, so that we can migrate the code base towards it.
    3333
    3434 * If a function does several things in a regular way, then it should look like that in the source code. This means you should line up arguments to similar function calls. For example, use this: