Changes between Version 29 and Version 30 of DevNotes/DevGuide/CodingRules


Ignore:
Timestamp:
Mar 17, 2017 5:53:29 AM (8 years ago)
Author:
pkienzle
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • DevNotes/DevGuide/CodingRules

    v29 v30  
    4141    * The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface. 
    4242    * The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its {{{ __init__ }}} method. Individual methods should be documented by their own docstring. 
    43      
     43    * Docstrings are processed by sphinx, and should use !ReStructuredText formatting conventions.     
    4444      
    4545    * Models: when adding a new model the .py file starts with an r (for raw) and three sets of quotes to start the doc string and ends with a second set of 3 quotes. 
    … …  
    153153    #!div style="font-size: 80%" 
    154154    {{{#!python         
    155     max_bins = 7 
    156     if i < max_bins: 
     155    MAX_BINS = 7 
     156    if i < MAX_BINS: 
    157157    }}} 
    158158    }}} 
    … …  
    182182    * Attributes of a good test: Fast, Clear, Isolated, Reliable 
    183183      
    184     * 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). 
     184    * Models: Include at least one test for each model and PLEASE make sure that the answer value is correct (i.e. don't blindly use the function return value to set the test results; instead check against the paper or another program). 
    185185    * Models: Remember to test a model for critical values (e.g. q=0) 
    186186 
    … …  
    190190    * Remember to add files using git add before committing your changes. 
    191191    * 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.   
     192    * Reference ticket numbers in commit message. 
    192193    * 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). 
     194    * Name branches after a ticket number where appropriate, such as ticket-835 for ticket #835. 
    193195    * When merging a branch with multiple commits use --squash or interactively rebase before pushing to master. 
    194196 
    … …  
    246248        }}} 
    247249    * All user accessible input/output data should be available through getters 
    248      {{{ __getattr__}}} and {{{__setattr__}}}} should be avoided. 
     250     {{{ __getattr__}}} and {{{__setattr__}}} should be avoided. 
    249251    * Main functionality should be exposed as a method with easy to understand name, e.g. calculate() and should return the results object/structure 
    250252    * When defining the interface, type hints are an important part of the definition. Type hints are described in PEP-484 https://www.python.org/dev/peps/pep-0484 and should be added for all API methods.