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

Timestamp:

May 30, 2016 5:47:54 AM (8 years ago)

Author:

wojciech

Comment:

—

DevNotes/DevGuide/CodingRules

@@ -144 +144 @@
 Comments in the code
 
-    Comments should usually be complete sentences.
-    Use block comments to talk about the code immediately following the comments.
-    Use inline comments (sparingly) to clarify confusing lines.
+    * Comments should usually be complete sentences.
+    * Use block comments to talk about the code immediately following the comments.
+    * Use inline comments (sparingly) to clarify confusing lines.
 
 Testing
 
-    Unit tests should test one method only. This allows you to easily identify what failed if the test fails.
-    Unit tests should not be coupled together, therefore one unit test CANNOT rely on another unit test having completed first.
-    Unit tests should use small and simple data sets.
-    Tests should be fast, ideally really fast - certainly not more than a few seconds.
-    Untestable code is a code-smell, if you can't get the code under test it probably needs refactoring.
-    Weight your testing to be destructive rather than demonstrative. Destructive tests are more efficient in finding bugs.
-    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.
-    Attributes of a good test: Fast, Clear, Isolated, Reliable
+    * Unit tests should test one method only. This allows you to easily identify what failed if the test fails.
+    * Unit tests should not be coupled together, therefore one unit test CANNOT rely on another unit test having completed first.
+    * Unit tests should use small and simple data sets.
+    * Tests should be fast, ideally really fast - certainly not more than a few seconds.
+    * Untestable code is a code-smell, if you can't get the code under test it probably needs refactoring.
+    * Weight your testing to be destructive rather than demonstrative. Destructive tests are more efficient in finding bugs.
+    * 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.
+    * Attributes of a good test: Fast, Clear, Isolated, Reliable
      
-    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).
-    Models: Remember to test a model for critical values (e.g. q=0)
+    * 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).
+    * Models: Remember to test a model for critical values (e.g. q=0)
 
 GIT
 
-    Remember to add files using git add before committing your changes.
-    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.  
+    * Remember to add files using git add before committing your changes.
+    * 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.  
     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).
-    When merging a branch with multiple commits use --squash or interactively rebase before pushing to master.
+    * When merging a branch with multiple commits use --squash or interactively rebase before pushing to master.
 
 Code Reviews
 
-    Code reviews by another developer are encouraged for minor functionality and required for major changes
-    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
-    Follow the standard practices:
-        Review no more than 400 lines of code at a time
-        Take your time. Inspection rates should be under 500 LOC per hour
-        Don't review code for more than 90 minutes at a time
-        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)
-        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)
-        Remember to review related unit tests - they are as important as the code.
-        Verify that the defects are actually fixed
+    * Code reviews by another developer are encouraged for minor functionality and required for major changes
+    * 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
+    * Follow the standard practices:
+        1. Review no more than 400 lines of code at a time
+        2. Take your time. Inspection rates should be under 500 LOC per hour
+        3. Don't review code for more than 90 minutes at a time
+        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)
+        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)
+        6. Remember to review related unit tests - they are as important as the code.
+        7. Verify that the defects are actually fixed
 
 Editors
 
-Tips and tricks of how to make your life easier when developing code with your favorite editor.
-
-Example editors used in the group are:
-
-    vi
-    PyCharm
-    Visual Studio with PTVS
-
-Both PyCharm and VS allow source level debugging both of self-spawned processes and by attaching to an already running process.
+    * Tips and tricks of how to make your life easier when developing code with your favorite editor.
+    * Example editors used in the group are:
+       1. vi
+       2. PyCharm
+       3. Visual Studio with PTVS
+
+     * Both PyCharm and VS allow source level debugging both of self-spawned processes and by attaching to an already running process.
 
 API