[wingide-users] Question/Suggestion: More docstrings

[Tom Stambaugh]

Hi All,

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 
receiver.
- Collects the cached subAssembly corresponding to aSubAssemblyBuilder.
- Collects its classNames
- For each className, collects its versionId
- Forms and answers a map where:
     key: className
     value: versionId
"""

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."

Thanks,
Tom
-- 
Tom Stambaugh, Founder
Zeetix LLC/ZeeGuide/ZeeForge
27 Auburn Street
Brookline, MA 02446
617-734-8934 (land)
617-721-0446 (cell)