[Python-Dev] styleguide inconsistency
I was recently searching for some guidance on how to name packages and modules, and discovered an inconsistency in the style guides published at www.python.org. http://www.python.org/doc/essays/styleguide.html says Module names can be either MixedCase or lowercase. That page also refers to PEP 8 at http://www.python.org/dev/peps/pep-0008/, which says Modules should have short, all-lowercase names. ... Python packages should also have short, all-lowercase names Some discussion on dev.lang.python has so far turned up the following points of view: 1) There isn't technically a contradiction because can be is not the same as should be. However, since this is a style guide and not a syntax guide, I still think the documents are contradictory. 2) There isn't any confusion because the styleguide refers to the PEPs, so they have priority. However, styleguide.html does not explain that the PEPs are more up-to-date. We shouldn't expect someone to go to the PEPs after finding an answer to their question in the styleguide. Perhaps one of these documents could be revised to make the situation more clear? Thanks, Darren Dale ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] styleguide inconsistency
On 4/23/07, Darren Dale [EMAIL PROTECTED] wrote: I was recently searching for some guidance on how to name packages and modules, and discovered an inconsistency in the style guides published at www.python.org. http://www.python.org/doc/essays/styleguide.html says Module names can be either MixedCase or lowercase. That page also refers to PEP 8 at http://www.python.org/dev/peps/pep-0008/, which says Modules should have short, all-lowercase names. ... Python packages should also have short, all-lowercase names Some discussion on dev.lang.python has so far turned up the following points of view: 1) There isn't technically a contradiction because can be is not the same as should be. However, since this is a style guide and not a syntax guide, I still think the documents are contradictory. 2) There isn't any confusion because the styleguide refers to the PEPs, so they have priority. Yes, the PEPs take priority. However, styleguide.html does not explain that the PEPs are more up-to-date. The PEPs are more up-to-date. We shouldn't expect someone to go to the PEPs after finding an answer to their question in the styleguide. Perhaps one of these documents could be revised to make the situation more clear? I personally think the style guide should just go and/or redirect to PEP 8. I didn't even know it existed until this email. And I only know of people updated PEP 8. -Brett ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] styleguide inconsistency
On Mon, Apr 23, 2007 at 09:25:48AM -0700, Brett Cannon wrote: I personally think the style guide should just go and/or redirect to PEP 8. I didn't even know it existed until this email. And I only know of people updated PEP 8. The top of the style guide basically does that: This style guide has been converted to several PEPs (Python Enhancement Proposals): PEP 8 for the main text, PEP 257 for docstring conventions. See the PEP index. Perhaps that warning could be strengthened to suggest that the style guide is outdated and (apparently) unfinished? Beyond that, I don't see any contradiction here, and I don't see any reason to spend time updating the style guide. Dustin ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] styleguide inconsistency
Someone should just take down that styleguide, or *replace* it with a link (and only a link) to PEP 8. I can't do that myself, it's in the hands of the webmasters. On 4/23/07, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: On Mon, Apr 23, 2007 at 09:25:48AM -0700, Brett Cannon wrote: I personally think the style guide should just go and/or redirect to PEP 8. I didn't even know it existed until this email. And I only know of people updated PEP 8. The top of the style guide basically does that: This style guide has been converted to several PEPs (Python Enhancement Proposals): PEP 8 for the main text, PEP 257 for docstring conventions. See the PEP index. Perhaps that warning could be strengthened to suggest that the style guide is outdated and (apparently) unfinished? Beyond that, I don't see any contradiction here, and I don't see any reason to spend time updating the style guide. Dustin ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/guido%40python.org -- --Guido van Rossum (home page: http://www.python.org/~guido/) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
