[Doc-SIG] How should variables' docstrings be written?

John M. Gabriele john_sips_tea at yahoo.com
Fri Mar 17 19:31:18 CET 2006


--- Edward Loper <edloper at gradient.cis.upenn.edu> wrote:

> [snip]
> 
> Comment that begins with a special marker string:
>    This is my current favorite.  [snip]
>    The markers that look
>    reasonably good to my eye are:
> 
>      #: #| #*
> 
> [snip]
> 
> So..  Which conventions do people prefer?
> 
> -Edward
> 

I like that one too because it saves space and also b/c
it comes before the variable. I never understood why
docstrings come *after* the thing they're describing...

Anyway, I think any of your suggestions look pretty good
to the eye, and with proper syntax highlighting they will
all stand out nicely in one's editor.

I'd prefer #@ or #% though, since they're easier to type.
I can hold down the shift key with my right pinky and
just hit those two keys (3-2 or 3-5) very quickly without
missing a beat.

---John


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 


More information about the Doc-SIG mailing list