On Wednesday, May 2, 2012 2:38:42 PM UTC-7, Simon King wrote: > > Hi Michael, > > On 2012-05-02, Michael Orlitzky wrote: > > You can usually call the underscore methods directly. > > I thought (i.e.: I am sure that I was repeatedly told) that calling > magical methods in a doctest is strongly discouraged. The reason is > that one purpose of doctests is educational. As a reviewer, I would > not hesitate to ask for changing such an overly explicit test, when > the doctest fails to show how the method is really supposed to be > used. Of course, `_repr_` and friends is not supposed to be called > directly - hence the indirect test. >
I've never heard of such a rule. I notice that the Developer's Guide needs to be updated: I can't find mention of "indirect doctest" anywhere there, so there is obviously no mention of how or when it should be used. Indeed, I can't find "indirect doctest" in any documentation except for the reference manual. Also, I believe that the Sage coverage script doesn't require an indication of '# indirect doctest' for doctests for underscore methods; it is assumed (I guess) that in those cases, you may very well doctest those indirectly. For example, the file sage/homology/delta_complex.py has a method '__cmp__' in which the doctests don't call it explicitly, there is no '# indirect doctest' anywhere, and yet the file has 100% coverage. I found several other such examples browsing through the source code and searching for "def _". Anyway, as far as whether you should directly call the method, I think arguments can be made on both sides. An explicit call to the method is convincing, and since these methods aren't included in the reference manual (at least not right now), the educational aspect is not as great. However, for people browsing the code, using the methods (indirectly) in the intended way can be helpful. For indirect doctests, either marked explicitly or not, it's up to the author and the referee to make sure that the doctest actually calls the method being tested, obviously. Other than that, I personally think it's best not to have a policy one way or the other. -- John -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
