On Wed, May 10, 2017 at 1:42 PM, Michael Orlitzky <mich...@orlitzky.com> 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 by "function"? Here is an example, taken from >> ticket #21399: >> >> | >> importsys >> >> ifsys.platform ==X: >> defauxiliary_function(...): >> ... >> elifsys.platform ==Y: >> defauxiliary_function(...): >> ... >> else: >> defauxiliary_function(...): >> ... >> >> defmain_function(...): >> returnauxiliary_function(...) >> | >> >> What needs a docstring here? What needs doctests? >> > > > You can write this in a way that lets you doctest everything... > > def auxiliary_function_X: > ... > > def auxiliary_function_Y: > ... > > def auxiliary_function_default: > ... > > def main_function(platform = None): > if platform is None: > platform = sys.platform > > if platform == X: > return auxiliary_function_X() > elif platform == Y: > return auxiliary_function_Y() > else: > return auxiliary_function_default()
This is still pretty needless refactoring. It's pointless to define each function when only one will ever be relevant on the current platform. If you think in terms of C, it might not even be possible to *compile* each platform-specific implementation. In Python that's far less likely to be an issue, albeit not unheard of either (for example, a Windows-specific implementation might import the "msvcrt" module, not present on other platforms--you could move the import to inside the function call but this is just implementing bad practice for no reason). 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. -- 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.
