Changes between Version 16 and Version 17 of Development/CodeConventions

Show
Ignore:
Timestamp:
03/16/10 06:56:47 (4 years ago)
Author:
benl (IP: 129.94.242.47)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CodeConventions

    v16 v17  
    1616 * Each top-level definition should have a comment explaining what it is for. One liners are fine. 
    1717 
    18  * 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. 
     18 * 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. 
    1919 
    2020 * 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: