[wingide-users] Question/Suggestion: More docstrings
tms at zeetix.com
Fri Mar 5 11:25:41 MST 2010
In response to this:
> This hasn't come up before, as far as I can remember, so I'm not sure how
> often people really use these other docstring forms. I could see that
> "attribute docstrings" would be useful, though. I don't get the point of
> "additional docstrings", however.
I've *always* used "additional docstrings" to elaborate the one-line
docstring associated with each class and method. Perhaps I've
misunderstood the community practices for years, but here's the way I
thought all this worked (and is the way I've written all my code):
1. The docstring is a one-line summary that describes the class or
method. For methods, in particular, it uses an active voice and really
does fit on one (possibly long) line ("""Answers a map associating the
name and versionId of each asset contained in aSubAssemblyBuilder."""")
2. There is, from time to time, a need for additional detail describing
subtle behavior or conditions. This additional detail is provided by an
elaboration of the docstring, at the same indent level. For example:
"""This only works when aSubAssemblyBuilder is already cached in the
- Collects the cached subAssembly corresponding to aSubAssemblyBuilder.
- Collects its classNames
- For each className, collects its versionId
- Forms and answers a map where:
3. Each is a triple-quoted string.
4. The "docstring" is used as in WingIDE. The additional detail is used
by subsequent developers who may need to understand what the method is
doing and why.
When I ramped up on Python (around 2003 or so), I relied on material and
practices from Guido and also (heavily) from the Chandler project. My
background is from Smalltalk, so that further corrupts my coding style.
I wanted to offer just one datapoint for how I use "additional docstrings."
Tom Stambaugh, Founder
27 Auburn Street
Brookline, MA 02446
More information about the wingide-users