Changes between Version 17 and Version 18 of Development/CodeConventions

Show
Ignore:
Timestamp:
03/16/10 07:03:41 (5 years ago)
Author:
benl (IP: 129.94.242.47)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v17 v18  
    1010== General Rules for all Languages == 
    1111 
     12=== Spacing === 
    1213 * Tabs are 8 spaces. The reason being that when you `cat` a text file to a unix console they come out as 8 spaces. No further discussion will be entered into on this point.  
    1314 
    1415 * We prefer literal tabs at the start of lines instead of hard spaces. 
    1516 
     17 
     18=== Comments === 
    1619 * Each top-level definition should have a comment explaining what it is for. One liners are fine. 
    1720 
    1821 * 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. For `n` lines of code there are potentially `n^2` bugs (at least), so we want to know exactly what each line is trying to achieve. 
    1922 
     23 * 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. 
     24 
     25=== Layout === 
    2026 * 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: 
    2127{{{ 
     
    3238   }}} 
    3339 
    34  * 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. 
    3540 
     41 
     42=== Naming === 
    3643 * Name conversion functions like ` globOfTops :: [Top] -> Glob ` instead of ` topsToGlob :: [Top] -> Glob`. The type may be the opposite way around compared to the name, but it makes the source code easier to read. Consider ` (globOfTops someTops) ` vs ` (topsToGlob someTops)`.  
    3744 
    3845 * 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`. 
     46 
     47=== Structure === 
     48 * 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. 
     49 
    3950 
    4051[[br]]