[Python-Dev] Breaking undocumented API

[Ron Adam]

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.

<shrug>


>> 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?