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 actually be used. However, for internal functions or > things like __init__, it is often not easy to write meaningful > docstrings. Something I regularly see is that people literally write the > same doctest twice in two different places (say, an end-user function > and an internal function) just to satisfy a stupid script. >
I like that we err on the side of safety. Even internal functions need to be documented: * What is the function for? What is it supposed to do? * What parameters does it take? What are their default values? * What does it return? * Does it throw any exceptions? * Can you show me an example of how I might call it? All of those are just as useful to me as a developer as they would be for the user of the e.g. matrix() function. Enforcing the doctest rule ensures that the necessary documentation is there. You might wind up with some extra verbosity, but if you get rid of the rule, people just won't write docs. As an example, consider pretty much any project on Github that doesn't have a "you must document your functions" rule. The Sage source code is much nicer to work with than most projects, largely due to that rule. -- 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.
