On Mon, May 15, 2017 at 5:26 PM, William Stein <wst...@gmail.com> wrote: > On Mon, May 15, 2017 at 6:56 AM, Erik Bray <erik.m.b...@gmail.com> wrote: > [...] >> In PEP-8, Python's style guide for Python code, there's an admonition >> right at the beginning titled "A Foolish Consistency is the Hobgoblin >> of Little Minds" (the wording is tongue-in-cheek; don't take it >> literally!): https://www.python.org/dev/peps/pep-0008/#id15 >> >> The point is that no matter how well motivated a coding guideline is >> it's just that--a guideline (maybe even a very important one!). But >> one never bend over backwards to write non-idiomatic, convoluted, or >> not well-motivated code just to satisfy a guideline. The guideline >> should absolute be *considered* strictly when reviewing some code, >> especially if it's critical mathematical code (in the case of Sage). >> But that doesn't mean there will never be exceptions where one can't >> use their common sense. > > +1, but... > > <ancient history> > > The reason for the "100% doctest policy" is because in 2007 during a > discussion at Sage Days 5 (see [1]) Craig Citro proposed "We should > require 100% doctesting in new code". Many other people in the room > and I thought this sounded like a good idea and interesting challenge, > since Sage was starting to rapidly grow at the time. I wrote a > coverage script to see where we stood and it was fun to include the > stats with each new release. The stats are *very* impressive to me > today: > > ~/sage/src/sage$ ../../sage -coverage --summary . > Global score: 96.1% (42697 of 44428)
Oh, neat! Though it would be nice to actually be able to use existing runtime code coverage tools get a real view of how much the tests are covering. As I said before there are of course limitations, but it helps to find major use cases that aren't being tested. It's possible using something like coverage.py will just work, but I haven't tried it yet. > We quickly started realizing how incredibly useful Craig's suggestion > was in practice, and that it was clearly going to be absolutely > critical to growing our developer base beyond a handful of people. > Also, being able to take absolutely any function in the code, and > paste something into the sage: prompt that interactively exercised > that function was also very useful. Moreover, it was shocking the > extent to which anybody touching since matrices over the rationals > could easily break something else "far away" in modular forms (heh -- > it happened today! [2])... > > The only serious challenge to this policy that I recall was when > Michael Abshoff merged a massive amount of non-doctested quadratic > forms code from Jon Hanke in 2008. I was pretty annoyed and ensured > that the code was properly tested in a timely manner. > > </ancient history> Thanks for the background. And of course, I think it's a great policy by and large. It's just important to be clear what we mean when we ask whether or not a function is "tested". If you wrap a function immediately in a wrapper function, the purpose of which is to supply documentation/tests in one place, then the wrapped function is being tested--you don't need a formal proof to see that. It's just a simple application of the DRY principle :) -- 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 https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
