[Python-Dev] Tweaking PEP 8 guidelines for use of leading underscores

[Brett Cannon]

On Sun, Jul 14, 2013 at 8:01 PM, Cameron Simpson <cs at zip.com.au> wrote:

> On 15Jul2013 09:48, Steven D'Aprano <steve at pearwood.info> wrote:
> | On 14/07/13 21:09, Nick Coghlan wrote:
> |
> | >Slight adjustment to the proposed wording to ensure completely
> undocumented
> | >modules are also considered private:
> |
> | -1 on this adjustment. If somebody cannot be bothered writing a one-line
> doc string:
> |
> | "This module is private, don't touch."
> |
> | then they certainly shouldn't be allowed to use up a public name for a
> private module. I don't think we should be encouraging more private,
> undocumented modules. (Documentation is valuable even for private modules.)
> |
> | I'd go further, and say that no more private modules should be accepted
> for the std lib unless they have a leading underscore. I suppose for
> backwards compatibility reasons, we probably can't go through the std lib
> and rename private modules to make it clear they are private, but we don't
> have to accept new ones without the underscore.
>
> I disagree.
>
> A private module is a perfectly sane way to implement the internals
> of something, especially if it is subject to implementation change
> in the future.
>
> Clarification: is Nick classifying a module with docstrings by no
> content in the "modules" section of the Python doco as undocumented?
>

Yes. This has nothing to do with docstrings, just the official
documentation at docs.python.org.


> That is what I would presume; I'd expect the code to be littered
> with docstrings anyway, but the module as a whole is not presented
> in the documentation and so should be private and not relied upon.
>

Exactly.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130714/d466ee04/attachment.html>