[Python-Dev] Breaking undocumented API
rrr at ronadam.com
Tue Nov 9 05:28:32 CET 2010
On 11/08/2010 07:18 PM, Brett Cannon wrote:
> On Mon, Nov 8, 2010 at 16:10, Ron Adam<rrr at ronadam.com> wrote:
>> def _private_api():
>> # Isn't it a good practice to use comments here?
> That is ugly. I already hate doing that for unittest, I'm not about to
> champion that for anything else.
Ugly? I suppose it's a matter of what you are used to.
> It would also lead to essentially requiring a docstrings for
> everything that is public whether someone wants to bother to writing a
> docstring or not. I don't think we should be suggesting that a
> docstring be required either.
I can see where that would be overly strict in an application or script
made with python.
But it seems odd to me, to have undocumented api's in a programming
language. If it's being replaced with something else, the doc string can
say that. A null string is also a valid doc string if you just need a
place holder until someone gets to it.
>> Brett, I'm sure you can up with a better alternative. ;-)
> But I don't want to have to do that in the stdlib by remembering what
> modules I should or should not import. This is just as much about
> developer burden on core devs as it is making sure we don't yank the
> rug out from underneath users.
Yes, I agree. But how to best do that?
More information about the Python-Dev