Changes between Version 12 and Version 13 of DevNotes/DevGuide/CodingRules


Ignore:
Timestamp:
May 30, 2016 7:47:54 AM (6 years ago)
Author:
wojciech
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • DevNotes/DevGuide/CodingRules

    v12 v13  
    144144Comments in the code 
    145145 
    146     Comments should usually be complete sentences. 
    147     Use block comments to talk about the code immediately following the comments. 
    148     Use inline comments (sparingly) to clarify confusing lines. 
     146    * Comments should usually be complete sentences. 
     147    * Use block comments to talk about the code immediately following the comments. 
     148    * Use inline comments (sparingly) to clarify confusing lines. 
    149149 
    150150Testing 
    151151 
    152     Unit tests should test one method only. This allows you to easily identify what failed if the test fails. 
    153     Unit tests should not be coupled together, therefore one unit test CANNOT rely on another unit test having completed first. 
    154     Unit tests should use small and simple data sets. 
    155     Tests should be fast, ideally really fast - certainly not more than a few seconds. 
    156     Untestable code is a code-smell, if you can't get the code under test it probably needs refactoring. 
    157     Weight your testing to be destructive rather than demonstrative. Destructive tests are more efficient in finding bugs. 
    158     Use long and descriptive names for testing functions. The reason is testing functions are never called explicitly. square() or even sqr() is ok in running code, but in testing code you would have names such as test_square_of_number_2(),test_square_negative_number(). These function names are displayed when a test fails, and should be as descriptive as possible. 
    159     Attributes of a good test: Fast, Clear, Isolated, Reliable 
     152    * Unit tests should test one method only. This allows you to easily identify what failed if the test fails. 
     153    * Unit tests should not be coupled together, therefore one unit test CANNOT rely on another unit test having completed first. 
     154    * Unit tests should use small and simple data sets. 
     155    * Tests should be fast, ideally really fast - certainly not more than a few seconds. 
     156    * Untestable code is a code-smell, if you can't get the code under test it probably needs refactoring. 
     157    * Weight your testing to be destructive rather than demonstrative. Destructive tests are more efficient in finding bugs. 
     158    * Use long and descriptive names for testing functions. The reason is testing functions are never called explicitly. square() or even sqr() is ok in running code, but in testing code you would have names such as test_square_of_number_2(),test_square_negative_number(). These function names are displayed when a test fails, and should be as descriptive as possible. 
     159    * Attributes of a good test: Fast, Clear, Isolated, Reliable 
    160160      
    161     Models: Include at least one test for each model and PLEASE make sure that the answer value is correct (i.e. not a random number). 
    162     Models: Remember to test a model for critical values (e.g. q=0) 
     161    * Models: Include at least one test for each model and PLEASE make sure that the answer value is correct (i.e. not a random number). 
     162    * Models: Remember to test a model for critical values (e.g. q=0) 
    163163 
    164164GIT 
    165165 
    166     Remember to add files using git add before committing your changes. 
    167     Have a self-explanatory commit message. "Merged with master" is not sufficient. It is a good practice to do a git log before pushing to master and check for the top message. git commit --amend can be used to fix commit message if we are not satisfied with it.   
     166    * Remember to add files using git add before committing your changes. 
     167    * Have a self-explanatory commit message. "Merged with master" is not sufficient. It is a good practice to do a git log before pushing to master and check for the top message. git commit --amend can be used to fix commit message if we are not satisfied with it.   
    168168    Using git branches is encouraged when developing new features or implementing significant changes. It is also a good habit to regularly merge you branch with master as well as push it Github (as a backup). 
    169     When merging a branch with multiple commits use --squash or interactively rebase before pushing to master. 
     169    * When merging a branch with multiple commits use --squash or interactively rebase before pushing to master. 
    170170 
    171171Code Reviews 
    172172 
    173     Code reviews by another developer are encouraged for minor functionality and required for major changes 
    174     When developing in the branch it is easy to ask for pull requests. One can also test your code easily by pulling your branch and not messing up with master branch 
    175     Follow the standard practices: 
    176         Review no more than 400 lines of code at a time 
    177         Take your time. Inspection rates should be under 500 LOC per hour 
    178         Don't review code for more than 90 minutes at a time 
    179         Authors should annotate source code before the review. (Annotations guide the reviewer through the changes, showing which files to look at first and defending the reason behind each code modification. Annotations should be directed at other reviewers to ease the process and provide more depth in context) 
    180         Use checklists - they substantially improve results for both authors and reviewers (It's very likely that each person on your team makes the same 10 mistakes over and over. Omissions in particular are the hardest defects to find because it's difficult to review something that isn't there. Checklists are the most effective way to eliminate frequently made errors and to combat the challenges of omission finding) 
    181         Remember to review related unit tests - they are as important as the code. 
    182         Verify that the defects are actually fixed 
     173    * Code reviews by another developer are encouraged for minor functionality and required for major changes 
     174    * When developing in the branch it is easy to ask for pull requests. One can also test your code easily by pulling your branch and not messing up with master branch 
     175    * Follow the standard practices: 
     176        1. Review no more than 400 lines of code at a time 
     177        2. Take your time. Inspection rates should be under 500 LOC per hour 
     178        3. Don't review code for more than 90 minutes at a time 
     179        4. Authors should annotate source code before the review. (Annotations guide the reviewer through the changes, showing which files to look at first and defending the reason behind each code modification. Annotations should be directed at other reviewers to ease the process and provide more depth in context) 
     180        5. Use checklists - they substantially improve results for both authors and reviewers (It's very likely that each person on your team makes the same 10 mistakes over and over. Omissions in particular are the hardest defects to find because it's difficult to review something that isn't there. Checklists are the most effective way to eliminate frequently made errors and to combat the challenges of omission finding) 
     181        6. Remember to review related unit tests - they are as important as the code. 
     182        7. Verify that the defects are actually fixed 
    183183 
    184184Editors 
    185185 
    186 Tips and tricks of how to make your life easier when developing code with your favorite editor. 
    187  
    188 Example editors used in the group are: 
    189  
    190     vi 
    191     PyCharm 
    192     Visual Studio with PTVS 
    193  
    194 Both PyCharm and VS allow source level debugging both of self-spawned processes and by attaching to an already running process. 
     186    * Tips and tricks of how to make your life easier when developing code with your favorite editor. 
     187    * Example editors used in the group are: 
     188       1. vi 
     189       2. PyCharm 
     190       3. Visual Studio with PTVS 
     191 
     192     * Both PyCharm and VS allow source level debugging both of self-spawned processes and by attaching to an already running process. 
    195193 
    196194API