On Jun 12, 2010, at 4:10 AM, David Kirkby wrote:
On 12 June 2010 03:46, kcrisman <kcris...@gmail.com> wrote:
Notice I'm talking about actual practice as observed on actual
tickets, not 'official' policy. I think Sage does an excellent job
of
giving incentive for writing documentation, but there is far less
incentive for writing this sort of exhaustive documentation to catch
lots of edge cases until they are detected. And there is very
little
incentive to add documentation to *existing* functions to do this,
other than reaching various % coverage milestones - even though it
always uncovers interesting, occasional important, bugs.
And I'm not suggesting there should be some magic incentive, I am
speaking more in an Eric-Raymond quasi-economic sense here - what
does
a developer work on in limited time? Whatever 'scratches the itch'.
This is obvious in review - I think all of us have had patches
languish for months because someone didn't review them, even if the
reviews were simple and we asked nicely. In fact, this has happened
to me on a number of "improve documentation and fix bugs uncovered
while doing it" tickets :)
So much the more so with doc - there simply isn't this army of people
out there waiting to add huge amounts of doc, though some of us are
trying (and in Minh's case, succeeding).
Minh does an excellent job. I have a huge amount of respect for Minh.
I really believe he was by far the most worthy winner of the recent
Sage prize.
+1. Right now there's a big push to get more tests in. This can only
be a good thing, assuming people are writing good tests (and that's
what the referee procedures are for). I could see pushes in the future
for more documentation. Also, as more non-developer users start
getting involved, I could see documentation as a natural way for them
to contribute.
Everyone should write the kinds of tests the feel are most beneficial
to Sage, with the measurement (not the end goal) being 90% coverage
this time around.
Nor is there an army waiting
to police these things. I think that Nathann's comment about people
working on what they want to and leaving other things to others is
true - perhaps not ideal (!), but at least honest and based on
observation of actual practice.
A perfectly reasonable question is that if someone does not have
motivation,
ability or time to do a job properly, should they do that job?
By the definition of 'properly' used here, Sage would still be a
program about Algebra and Geometry Exploration. I stand by my
observation that very few tickets exemplify the sort of comprehensive
documentation I feel is being discussed. Why?
Usually, motivation - fix the bug, test that it's fixed, and move on.
It would be good practice to write a test to ensure that the bug does
not show up again.
I've lot count of the number of times I've seen tickets which aim to
fix a bug, only for the bug to resurface.
Bug fixes are *required* to be accompanied by tests to get positively
reviewed, at least for Sage library code. If stuff goes in without
regression tests, that's a failure on both the part of the author and
reviewer.
- Robert
--
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
