On 10/22/2022 4:58 PM, Paulo da Silva wrote:
Hi all!
What is the correct way, if any, of documenting a function/method?
1.
def foo(a,b):
""" A description.
a: Whatever 1
b: Whatever 2
"""
[snip]
5.
Any other ...
Any comments/suggestions are welcome.
Thanks.
Paulo
This is not a trivial question - not because it is hard but because it
is important, and more so when someone else needs to work with your
code. It's surprising how easy it is to forget these details about even
your own code. Here are some examples of how I like to document
functions and methods, mostly based on PEP-257, Docstring Conventions
(https://peps.python.org/pep-0257/) and Guido's style guide before it.
def make_title_from_headline(self, p, h):
"""From node title, return title with over- and underline- strings.
The leading symbol is chosen based on the indent level of
the node.
Note that might different from p.h because of, e.g.,
directive removal.
ARGUMENTS
p -- the node position whose indent level is to be used.
h -- the headline string to be processed.
RETURNS
a string
"""
Key points - include all the arguments and the return. Capitals help
lead the eye to the ARGUMENT and RETURNS blocks. If you use keyword
arguments, add a KEYWORD ARGUMENTS section.
def plot(self, stackposition=MAIN, clearFirst=True):
"""Plot a 2-D graph.
ARGUMENTS
self -- an instance of a PlotManager
stackposition -- an integer denoting which data set to plot.
clearFirst -- True if the previous plot should be cleared,
else False.
RETURNS
nothing
"""
Key point -- if the function/method returns nothing, say so.
class Dataset:
'''Class to represent a 2D curve.
ATTRIBUTES
xdata, ydata -- sequences holding the x or y data sets.
Must be the same length. May be lists or numpy
ndarrays.
auxDataset -- dictionary of auxiliary data sets (e.g., for holding
statistical information)
errorBands -- List of Datasets to hold errors
orig_filename -- file path, if any, used to load data (before
any transformations have been applied).
xaxislabel -- label text for the X axis label
yaxislabel -- label text for the Y axis label
figurelabel -- label text for the graph of this data
ymin -- minimum value for Y axis
ymax -- maximum value for Y axis
parms -- dictionary of parameters, Meant to store the
current values so they can be written to a file.
'''
If you have the space, these annotations could instead be placed in-line
in the class's __init__() method. But it's not often there is enough
space, and when they are in the docstring they will be extracted and
displayed by docstring tools, which is a good thing.
Sometimes it can happen that a function/method is is simple and clear
that its name, and the names of the arguments, make it obvious what
their meaning is. But that happens less often than you might think.
- Be concise, but choose clarity over brevity;
- Try to devise good, descriptive names as far as possible;
- A long list of arguments probably should be ordered alphabetically,
but could also be grouped, with each group ordered. Otherwise, it is
useful to list the parameters in the order they appear in the
function/method signature.
- Be consistent in your docstrings, but remember there will be times
that it makes more sense to relax the consistency.
--
https://mail.python.org/mailman/listinfo/python-list
