Changes between Version 18 and Version 19 of DevNotes/DevGuide/CodingRules


Ignore:
Timestamp:
May 30, 2016 9:04:25 AM (8 years ago)
Author:
wojciech
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • DevNotes/DevGuide/CodingRules

    v18 v19  
    4141    * There are two forms of docstrings: one-liners and multi-line docstrings. One-liners are for really obvious cases. They should really fit on one line. 
    4242    * Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. 
    43     * The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's docstring.) The docstring for a package (i.e., the docstring of the package's __init__.py module) should also list the modules and subpackages exported by the package. 
     43    * The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's docstring.) The docstring for a package (i.e., the docstring of the package's {{{ __init__.py }}} module) should also list the modules and subpackages exported by the package. 
    4444    * 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. 
    45     * 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. 
     45    * 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. 
    4646      
    4747      
    … …  
    5858    * Use box_car with underscores separating words for variable and method names. 
    5959    * Use box_car with underscores for namespaces & directories 
    60     * Use _box_car with a leading underscore for non-public methods and _CamelCase with a leading underscore for non-public classes. 
    61     * Never use __box_car__ with leading and trailing double underscores 
     60    * Use {{{ _box_car }}} with a leading underscore for non-public methods and _CamelCase with a leading underscore for non-public classes. 
     61    * Never use {{{ __box_car__ }}} with leading and trailing double underscores 
    6262    * Avoid one-letter variable names (unless is acceptable one letter variable name or it is justified by the math in the paper) 
    6363    * Don't make long variable names just to keep lint happy: 
    … …  
    111111      }}} 
    112112    * Avoid importing * from any module. This is a typically a waste of time and memory. This leads to bugs as well when for example you have "from math import *" and "from numpy import *" in the same file and then decide to reorder them.  It also makes for harder to understand code since you don't know where the symbols are coming from. 
     113    * {{{ from module import *}}} is acceptable in {{{ __init__.py }}} if {{{ module.__all__ }}} defines the set of names being exported. 
    113114 
    114115    * Imports should be grouped in the following order: 
    … …  
    124125    * Exceptions should not be used for flow control, unless there is a very good reason for it 
    125126    * Error codes from a method should never be returned - use exceptions 
     127    * Never use a blank except: statement since it interferes with KeyboardInterrupt.  At a minimum, use except Exception:. 
     128 
    126129 
    127130Coding Style 
    … …  
    139142    * Do not put spaces before commas, colons, or semicolons. 
    140143    * Put one space around operators. 
    141     * However one can use no spaces with operators of higher priority, e.g., y = a*x**2 + b*x + c. 
     144    * However one can use no spaces with operators of higher priority, e.g., {{{ y = a*x**2 + b*x + c}}}. 
    142145 
    143146Miscellaneous 
    … …  
    215218The proposed access to the core functionality should be consistent for all perspectives and straightforward to use. 
    216219 
    217     * All known input arguments should be set in __init__, during instantiation, with proper checks 
     220    * All known input arguments should be set in {{{__init__}}}, during instantiation, with proper checks 
    218221    * Additional input data can be set directly through the @property decorator 
    219222 
    … …  
    238241        }}} 
    239242    * All user accessible input/output data should be available through getters 
    240      __getattr__ and __setattr__ should be avoided. 
     243     {{{ __getattr__}}} and {{{__setattr__}}}} should be avoided. 
    241244    * Main functionality should be exposed as a method with easy to understand name, e.g. calculate() and should return the results object/structure 
    242245    * 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.