On Sat, Apr 04, 2015 at 06:40:26AM -0700, Volker Braun wrote:
> Besides violating every Python docstring guide that I know,
Reference please.
> its also inconsistent: You can't just sometimes list self as
> input and sometimes not.
Why not? There are other chunks of our docstrings that are optional,
and only included if they are non trivial.
> IMHO the right thing to do is to either
> A) structure the code such that methods are always applicable,
> eg. why have a method on coxeter group elements that doesn't
> apply to coxeter group elements? Or
That's certainly the ideal situation. Sometimes it's
possible. Sometimes it's overdesign. We don't have a separate class
for non negative integers or for prime integers. Usually people
complain that I tend to overdesign with too many classes :-).
> B) document what happens under OUTPUT (though ideally we'd have a
> RAISES section like the google docstring style). Which also gives you a
> chance to say what kind of exception is being raised since caller code
> might want to catch that:
The INPUT section is the natural place for specifying simple
preconditions on the individual arguments (e.g. `l` -- a list of non
negative integer). I don't see why we should make a special case for
``self``. And why we should prevent ourselves from using a natural
concise idiom for doing so.
I agree that it's nice to be specific about the behavior when the
preconditions are violated (introducing a standardized RAISES section
would definitely make sense). But only if it's not obvious (e.g.,
depending on the context, a TypeError or a ValueError). Besides, more
often than not, this information is best explained (and tested!) on an
example.
Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil" <nthi...@users.sf.net>
http://Nicolas.Thiery.name/
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
