Raymond Hettinger added the comment: Much of this is already in PEP 8 and doesn't need repeating. Also, the tone is somewhat judgmental, heavy handed, restrictive, and over-broad for my tastes.
The last part seems to imply that we're going to change existing code in a way that may break user code. Our whole goal is to make migrating to Python 3 easier. The next to last part may create a pressure to document and promise some things that may be implementation specific details. I think we should let PEP 8 serve as the primary guideline. For new code, try to be as clear as possible on public versus private. For existing code, any changes should be considered on a case by case basis to strike the best balance between useful documentation versus over-specification versus breaking existing code by privatizing that which was unintentionally made public. Also, when it comes to documentation, there are many things which are public (such as pickling support, every magic method available, etc) which aren't discussed for every single class. The reason for this is that it tends to fill the documentation with clutter, making it hard for the more useful information to stand out. ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue10894> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
