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

[Cameron Simpson]

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

Cheers,
-- 
Cameron Simpson <cs at zip.com.au>

I sometimes wish that people would put a little more emphasis upon the
observance of the law than they do upon its enforcement. - Calvin Coolidge