Le lundi 28 septembre 2015 08:46:12 UTC+2, Jori Mäntysalo a écrit : > > On Fri, 25 Sep 2015, Travis Scrimshaw wrote: > > >>> 2) What about `self` in docstrings? > > >> There was a discussion about this some time ago: > >> https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ > >> and the conclusion was that we should avoid to use ``self`` in the > >> documentation. > > > That was not my impression at all from reading that discussion. The > > conclusion was to not put ``self`` as an *input* argument. Volker was > > advocating that we should not even refer to either ``self`` or "this > > object". If a new user does not understand ``self``, then the user will > > likely have problems using Sage (and likely reading the [English] > > documentation). In particular, see William's first post on this other > > thread: it implies we use it far more often than "this object" and it is > > better practice wrt to explicitness. > > True, there was no clear consensus on the thread. (Except that INPUT shall > not contain `self`.) > > Apologies for having misinterpreted the conclusion of this thread. I've read it again and indeed there was no consensus, except for the INPUT section. Thanks Travis for pointing this.
> I like "the thing" instead of "``self``", but whatever is OK to me, as > long as it is unified. > A compromise would be to avoid ``self`` in the docstrings of public methods (the only ones read by end-users) but use it in the docstrings of private methods (to be read by developers). For long docstrings, in order to avoid numerous occurrence of "this object" or "this thing", one could write something like ... this object (denoted by ``self`` in what follows) ... and use ``self`` everywhere in the remaining of the docstring, for it is clear that ``self`` is totally unambiguous. Eric. -- 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.
