On Tue, May 9, 2017 at 9:14 PM, John H Palmieri <[email protected]> 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: > > import sys > > if sys.platform == X: > def auxiliary_function(...): > ... > elif sys.platform == Y: > def auxiliary_function(...): > ... > else: > def auxiliary_function(...): > ... > > def main_function(...): > return auxiliary_function(...) > > What needs a docstring here? What needs doctests? > > - each instance of auxiliary_function? > - main_function? > > Several comments: > > - Perhaps in this case the doctests for the different functions would end up > being redundant. The docstrings shouldn't be, since there are specific > reasons for treating the platforms differently.
I don't agree with this because I don't think that's necessarily a proper use of docstrings. I see docstrings as primarily information for users of a function. It *may* provide some information about why / how the function is implemented if relevant, but not necessarily. It may also contain doctests, but again these serve as useful examples to the reader. However, information that is purely a development note like "we override this function here because of this bug" is purely a development note and what comments were made for. Especially for an internal function definition that a user would never see--you're just wasting (and admittedly trivial amount of) memory for a comment that has no use at runtime. -- 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 [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
