Changes between Version 4 and Version 5 of DevNotes/DevGuide/CodingRules


Ignore:
Timestamp:
May 30, 2016 7:08:19 AM (8 years ago)
Author:
wojciech
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • DevNotes/DevGuide/CodingRules

    v4 v5  
    3737    When in doubt, the best is to follow PEP 257 (https://www.python.org/dev/peps/pep-0257/). A few rules that are particularly recommended to follow are mentioned below: 
    3838 
    39     *All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. 
    40     *For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. 
    41     *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. 
    42     *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. 
    44     *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. 
     39    * All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. 
     40    * For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. 
     41    * 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. 
     42    * 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. 
     44    * 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. 
    4646      
    4747      
    48     *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. 
    49     *Models: wherever possible, try to use images of math functions with Latex equivalents. You can use the live demo Mathjax page ( http://www.mathjax.org/) to make sure the equation looks as expected. Also a lot of the Latex code can be taken from (or edited) from the PDF document created by Paul Kienzle:  [http://sasview.org/attachment/wiki/SasModels%20Work%20Package/Equations.docx.pdf] 
    50     *Models: don't add/remove the table of parameters which will get autogenerated. 
    51     *Models: add non-math figures to the sasmodels/sasmodels/models/img subdirectory and rename them to something sensible. 
    52     *Models: figure captions should be indented relative to the image tag. This allows us to, for example, change the font of the caption through CSS. 
    53     *Models: don't add the figure number since this will be generated automatically. 
    54     *Models: make sure all references to model parameters are appropriately named, and that the relationship between equation variables and model parameters are obvious. 
     48    * 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. 
     49    * Models: wherever possible, try to use images of math functions with Latex equivalents. You can use the live demo Mathjax page ( http://www.mathjax.org/) to make sure the equation looks as expected. Also a lot of the Latex code can be taken from (or edited) from the PDF document created by Paul Kienzle:  [http://sasview.org/attachment/wiki/SasModels%20Work%20Package/Equations.docx.pdf] 
     50    * Models: don't add/remove the table of parameters which will get autogenerated. 
     51    * Models: add non-math figures to the sasmodels/sasmodels/models/img subdirectory and rename them to something sensible. 
     52    * Models: figure captions should be indented relative to the image tag. This allows us to, for example, change the font of the caption through CSS. 
     53    * Models: don't add the figure number since this will be generated automatically. 
     54    * Models: make sure all references to model parameters are appropriately named, and that the relationship between equation variables and model parameters are obvious. 
    5555 
    5656Naming