I think the current policy is pretty absolute - even tiny little utility functions should have a test. Another developer might find and use your utility function, and having a test/example provides a sort of documentation that can be very useful to someone skimming the code. The policy can be a little irritating in the short term but I think its important and worthwhile for the long-term maintainability of sage code. And of course, once exceptions are made it gets harder to decide where to draw the line. Just my thoughts, there is nothing official about my opinion. Cheers, M. Hampton
On Nov 28, 6:49 am, Simon King <[EMAIL PROTECTED]> wrote: > Dear developers, > > I have a couple of basic methods (such as "save part of the attributes > in some file" or "put some data on a to-do-list used by another > method"). I wonder if their doc strings need examples, for the > following reasons: > > 1. I think they are of internal use only, and a normal user doesn't > even need to know about their existence. So, the user doesn't need to > see an example for the basic method. > > 2. The methods are heavily used by high-level methods, so the basic > methods are in fact tested by the doc tests of the high-level methods. > But since they *are* tested, there is no need for a separate test of > the basic methods. > > 3. A developer might care about the basic methods. But since the basic > methods just comprise 5-10 lines, an example might not be needed. And > I have comments in the code telling what the basic method does. > > So, I tend to have the following doc-string for a basic 'export' > method used in a high-level method 'blah' > "Of internal use only. Export data to disk. Implicit test in 'blah'" > > What is the official opinion on that matter? > Yours, > Simon --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to sage-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
