Changes between Version 36 and Version 37 of Development/CodeConventions


Ignore:
Timestamp:
Dec 5, 2012, 12:25:54 PM (6 years ago)
Author:
benl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v36 v37  
    66If 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...
    77
    8 == General Rules for all Languages ==
    9 
    10 === Comments ===
     8== Comments ==
    119 * '''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.
    1210
     
    2523
    2624
    27 === Spacing ===
     25== Spacing ==
    2826 * 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.
    2927
     
    3129
    3230
    33 === Layout ===
     31== Layout ==
    3432 * 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.
    3533
     
    6563
    6664
    67 === Naming ===
     65
     66== Naming ==
    6867
    6968 * Most names should use camel case style, but it's ok to use underscores in a postfix when naming different "versions" of a value. For example:
     
    8180 * If part of a variable name reflects its type, then put that part out the front. For example, source code variables of type `Shared.Var` should be named something like `vThing`, with a `v` out the front. Sets or lists of variables should be named `vsThing` with `vs` out the front. Avoid using names like `thingVar` and `thingVars`. We're not mandating Hungarian Notation, but if you're going to name a variable after a type anyway, then put the type part out the front.
    8281
    83 === Structure ===
     82== Structure ==
    8483 * Keep the sizes of the modules small. If a module has more than about 400 lines then consider breaking it up. Modules with just 100 lines are fine. Using small modules makes them easier to digest, forces you to think about the overall structure of the code, and helps parallel builds.
    8584
    86 
    87 [[br]]
    88 == Haskell / Disciple Specifics ==
    89 
    90 === Module signatures ===
     85== Module signatures ==
    9186Like the this, with the commas on the left:
    9287
     
    10196[[br]]
    10297
    103 === Try to put the {{{do}}} on the same line as the {{{=}}} ===
     98== Try to put the {{{do}}} on the same line as the {{{=}}} ==
    10499Use this:
    105100{{{
     
    118113The second version creates extra visual noise. As function names have different lengths, the column position of the top-level do will tend to be different between functions.
    119114
    120 === Put the $ on the left ===
     115== Put the $ on the left ==
    121116Like this:
    122117
     
    140135
    141136
    142 [[br]]
    143 === Prefer let over where ===
     137== Prefer let over where ==
    144138Prefer this:
    145139{{{