Changes between Version 32 and Version 33 of Development/CodeConventions


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

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v32 v33  
    22= Coding Conventions =
    33
    4 The 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. If you're not sure what the conventions are, then ask.
     4The 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 We don't want multiple coding styles in DDC. Having different styles creates "accidental complexity", that is, syntactic differences in the source that don't equate to real functional differences.
     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 use of library functions as much as formatting and commenting style. The DDC project was started some time ago, and times change...
     7
     8However: we try to avoid having multiple competing coding 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 conventions then they should be documented so the we can migrate the code base towards using them.
    79
    810[[br]]
    911== General Rules for all Languages ==
    1012
    11 === Spacing ===
    12  * Tabs are 8 spaces. The reason being that when you `cat` a text file to a unix console they come out as 8 spaces. Keep your editor set to tabs-as-8-spaces or you'll end up committing misaligned code.
     13=== Comments ===
     14 * 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 can.
    1315
    14  * 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.
    15 
    16 === Comments ===
    1716 * Each top-level definition should have a comment explaining what it is for. One liners are fine.
    1817
     
    2726
    2827 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.
     28
     29
     30=== Spacing ===
     31 * Tabs are 8 spaces. The reason being that when you `cat` a text file to a unix console they come out as 8 spaces. Keep your editor set to tabs-as-8-spaces or you'll end up committing misaligned code.
     32
     33 * 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.
    2934
    3035
     
    155160Using 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.
    156161
    157