[David Mertz]
 > I often use doctests to verify APIs and behaviors when I update code. I

> > know I'm in a minority and most developers slightly disparage doctests.

[Steven D'Aprano]

> I don't know why you think that "most developers" disparage doctests.
> Perhaps they're the same ones who think that "read the source" is all
> the documentation anyone needs.
>

Or ones who aren't happy unless they can demonstrate their mastery of a
convoluted class hierarchy with hundreds of methods to memorize.  Or unless
they're Guido!  He was never fond of doctest either.


I know I don't. I love them. Tim Peters loves them (he should, he wrote
> the module) and if its good enough for Uncle Timmy then anyone who
> disparages them better have a damn good reason.
>

Nope!  They don't need any reason at all.  I don't mind :-)

It was a sneaky, although minor, purpose of doctest to raise the bar for
making gratuitous changes to Python's output.  Developers have
approximately no appreciation for how off-putting it can be for users to
struggle with docs showing output they don't actually see.  Is the
installation buggy?  Did they type something wrong?  Was the doc author
just making stuff up?  Etc.  "Something's wrong here, but I don't know
what" is not a happy experience :-(

So I always count it as a Good Thing when someone points out "but doctests
will break".  _That_ developers can understand.  It's a proxy for the real
costs of making gratuitous changes, which are pretty much invisible to
developers.

Not that it should drive a decision - but it should be counted as _a_ cost.

...

I think we'd need to ask on Python-Dev to be sure, but my understanding
> is that backwards compatibility guarantees for reprs are weaker than
> those for regular APIs but stronger than those for error messages.
>

That sounds about right to me.  The docs for doctest already point out that
relying on reprs is dubious in various cases, so if someone is relying on
the repr of OrderedDict in their doctests they presumably care about the
repr more than the semantics.  Or they were just confused ;-)

In any case, since OrderedDict seems to be viewed as a legacy feature now,
making any change to it is an odd idea on the face of it.
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Reply via email to