Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Wed, May 17, 2017 at 1:53 PM, Jeroen Demeyer wrote: > On 2017-05-17 12:19, Vincent Delecroix wrote: >> >> 1) Each code path (including errors) must be tested". > > > You can easily translate this requirement as "require 100% *line* coverage" > instead of *function*

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 17/05/2017 14:00, Jeroen Demeyer wrote: On 2017-05-17 12:19, Vincent Delecroix wrote: Let me tell that my wish to have another test framework is mostly organizational. First of all, the code in the docstrings are intended to be read by users. I think that we would benefit from a clearer

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 05/17/2017 04:07 AM, Jeroen Demeyer wrote: > > Totally +1 > > Too bad that too many people take the coverage script too literal. > > For functions which are meant to be called directly by end users, > doctests are essential because they should show examples of how the > function should

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Wed, 17 May 2017, Jeroen Demeyer wrote: Here are several reasons: - random seeds are always the same That can easily be fixed by explicitly changing the random seed in the doctest (probably some helper context should be provided for this) Currently sage -t --randorder will give

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-17 12:19, Vincent Delecroix wrote: Here are several reasons: - random seeds are always the same That can easily be fixed by explicitly changing the random seed in the doctest (probably some helper context should be provided for this) - impossible to have complicated test

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-17 12:19, Vincent Delecroix wrote: 1) Each code path (including errors) must be tested". You can easily translate this requirement as "require 100% *line* coverage" instead of *function* coverage which is what is current sage-coverage script tests. 2) Introduce an

Re: [sage-devel] Sage policy question: require docstrings and doctests?

I do definitely support the idea of doctests for illustrative purposes. However, as already mentioned, relying on them for the whole testing framework is bad IMHO. Here are several reasons: - random seeds are always the same - impossible to have complicated test code - impossible to tune

Re: [sage-devel] Sage policy question: require docstrings and doctests?

> > For functions which are meant to be called directly by end users, > doctests are essential because they should show examples of how the > function should actually be used. For the case that a function is meant to be internal but can be accessed by an end user via say tab completion

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-15 18:39, Erik Bray wrote: It's possible using something like coverage.py will just work, but I haven't tried it yet. For Cython, see http://cython.readthedocs.io/en/latest/src/tutorial/profiling_tutorial.html#enabling-coverage-analysis -- You received this message because you

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-15 15:56, Erik Bray wrote: 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

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Mon, May 15, 2017 at 5:26 PM, William Stein wrote: > On Mon, May 15, 2017 at 6:56 AM, Erik Bray 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

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Mon, May 15, 2017 at 6:56 AM, Erik Bray 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 >

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Wed, May 10, 2017 at 1:42 PM, Michael Orlitzky wrote: > On 05/09/2017 03:14 PM, John H Palmieri wrote: >> Sage's developer's guide says: "Every function must have a docstring" >> which must include "An EXAMPLES block for examples. This is not >> optional." What is meant

Re: [sage-devel] Sage policy question: require docstrings and doctests?

I agree with Erik. > This distinction between docstrings vs. comments has never been the Sage > practice: Sage practice and official policy has always been to use > docstrings. Part of the point is that Sage has intentionally tried to blur > the line between user and developer, so any

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Wednesday, May 10, 2017 at 2:25:33 AM UTC-7, Erik Bray wrote: > > On Tue, May 9, 2017 at 9:14 PM, John H Palmieri > wrote: > > Sage's developer's guide says: "Every function must have a docstring" > which > > must include "An EXAMPLES block for examples. This is not

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 05/09/2017 03:14 PM, John H Palmieri wrote: > Sage's developer's guide says: "Every function must have a docstring" > which must include "An EXAMPLES block for examples. This is not > optional." What is meant by "function"? Here is an example, taken from > ticket #21399: > > | > importsys > >

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Tue, May 9, 2017 at 9:14 PM, John H Palmieri wrote: > Sage's developer's guide says: "Every function must have a docstring" which > must include "An EXAMPLES block for examples. This is not optional." What is > meant by "function"? Here is an example, taken from ticket

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Tue, 9 May 2017, John H Palmieri wrote: Sage's developer's guide says: "Every function must have a docstring" which must include "An EXAMPLES block for examples. This is not optional." Could we have that as a formal requirement, but allow something like EXAMPLES:: sage: pass #

[sage-devel] Sage policy question: require docstrings and doctests?

Sage's developer's guide says: "Every function must have a docstring" which must include "An EXAMPLES block for examples. This is not optional." What is meant by "function"? Here is an example, taken from ticket #21399: import sys if sys.platform == X: def auxiliary_function(...):