[Python-Dev] Breaking undocumented API (original) (raw)

Ron Adam 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 privateapi(): # # 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 mailing list