On Wed, Nov 17, 2010 at 2:34 AM, <exarkun at twistedmatrix.com> wrote: > I don't think it belongs only in PEP 8 (that's "a style guide" you're > referring to, correct?). It needs to be front and center. This is > information that every single user of the stdlib needs in order to use the > stdlib correctly. > > Imagine trying to use a dictionary without knowing about alphabetical > ordering. Or driving a car without knowing what lane markers indicate. The definition of the public/private policy in all its gory detail should be in PEP 8 as Guido suggests. The library documentation may then contain a note about the difference in compatibility guarantees for public and private APIs, say that any interface and behaviour documented in the manual qualifies as public, then point readers to PEP 8 for the precise details. A similar note could be placed in the C API documentation (with a reference to the detailed policy in PEP 7, perhaps REsTify'ing that PEP in the process in order to link directly to the naming convention section). Cheers, Nick. -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4