Python编码一致性规范

Python编码一致性规范Python编码一致性规范..................................................................................................................1什么是PEP...............................................................................................................................1PEP8..........................................................................................................................................1简介...................................................................................................................................1愚蠢的一致性就像没有脑子的妖怪...............................................................................2代码布局...................................................................................................................................2缩进...................................................................................................................................3制表符还是空格...............................................................................................................4单行最大长度...................................................................................................................4空白行...............................................................................................................................6源文件编码.......................................................................................................................6导入...................................................................................................................................6表达式与语句中的空白符.......................................................................................................8小问题...............................................................................................................................8其他建议.........................................................................................................................10注释.........................................................................................................................................11块注释.............................................................................................................................11行内注释.........................................................................................................................12文档字符串.....................................................................................................................12版本注记.................................................................................................................................12本文仅代表个人认知、观点、经验，MaybeStupid!什么是PEPPEP是PythonEnhancementProposal的缩写，翻译过来就是Python增强建议书。PEP8译者：本文基于2013-08-02最后修改的PEP8版本翻译，若要查看英文原文，请参考PEP8简介本文档给出的编码约定，来源于Python主发行版标准库中的代码。Python的C语言实现所使用的C语言风格指南，请参考PEP7。本文档与PEP257（文档字符串规范）都来自于Guido1)的PythonStyleGuido论文原文，另外有来自Barry'sstyleguide的补充。随着Python语言自身的改变，本指南也在持续演进，新的编码约定被认同，而旧的矣被废弃。许多项目都有一套专有的编码风格指南，当冲突发生时，应以项目编码规范为优先。愚蠢的一致性就像没有脑子的妖怪Guido的一个核心观点认为，相比于被编写，代码更多的是被阅读。这篇指南意在提高代码的可读性并使之在广袤的Python编码中保持风格一致。就像PEP20所表述的，“可读性当被重视2)”.风格指南即一致性指南。本文档中描述的一致性是重要的，一个项目内代码的一致性则更重要一些，而一个模块或方法中代码的一致性则是最重要的。但最终要的是：知道什么时候去打破一致性—风格指南并不总是适用。当存在不确定性时，做出你最好的抉择。你可以看看别人的代码是怎么写的，选择一种看起来最好的，并及时发问！特别注意：不要为了遵守本PEP而破坏代码的向后兼容性!当以下情况发生时，也是忽略某个风格指南的好理由：当遵守指南会降低代码可读性，甚至对于那些依循PEP去阅读代码的人也是这样时。当遵守指南会与其他部分的代码风格背离时—当然也许这是一个修正某些混乱代码的机会。当那些并没有遵循指南的旧代码已无法修改时。当你的代码需要与旧版本的Python保持兼容，而旧版本的Python不支持指南中提到的特性时。代码布局缩进每次缩进使用4个空格。续行3)应该与被圆括号、方括号、花括号包裹起来的其他元素对齐，或者使用悬挂式缩进。当使用悬挂式缩进时，应该遵循这些注意事项：第一行不能有参数，应该使用进一步的缩进来将续行与其他行区分开。符合本约定的代码：#Alignedwithopeningdelimiterfoo=long_function_name(var_one,var_two,var_three,var_four)#Moreindentationincludedtodistinguishthisfromtherest.deflong_function_name(var_one,var_two,var_three,var_four):print(var_one)不符合本约定的代码：#Argumentsonfirstlineforbiddenwhennotusingverticalalignmentfoo=long_function_name(var_one,var_two,var_three,var_four)#Furtherindentationrequiredasindentationisnotdistinguishabledeflong_function_name(var_one,var_two,var_three,var_four):print(var_one)可选的符合约定的代码：#Extraindentationisnotnecessary.foo=long_function_name(var_one,var_two,var_three,var_four)结尾的方括号/圆括号/花括号应该被放置在多行内容的最后一行的第一个非空字符的正下方4)，如下所示：my_list=[1,2,3,4,5,6,]result=some_function_that_takes_arguments('a','b','c','d','e','f',)或者被放置在多行内容的起始行的第一个字符的正下方5)，如下所示：my_list=[1,2,3,4,5,6,]result=some_function_that_takes_arguments('a','b','c','d','e','f',)制表符还是空格空格是首选的缩进方式。为了保持一致性，在使用了制表符作为缩进的代码中，应该保持使用制表符。Python3不支持空格缩进与制表符缩进混用。Python2中的混用缩进代码也应该被转换为统一使用空格。当使用-t选项来调用Python2命令行工具时，运行混用缩进的代码会报出警告，当使用-tt选项时，运行混用缩进的代码会报出错误。强力建议使用这两个选项。单行最大长度将所有的行限制在79个字符以内。对于那些具有很少的结构约束（例如文档字符串、注释）的代码段来说，最大行长度应该在在72个字符以内。限制代码编辑窗口的宽度使并排编辑多个文件成为可能，并且在使用代码审核工具时，可以很好的在两个相邻列中显示不同的代码版本。很多工具中的默认换行设置破坏了代码的可视结构，使其更难被理解。某些编辑器在换行时会在行尾放置标记字符，若限制代码的最大的长度，可以在这些最大宽度只有80个字符的编辑器中避免换行。而一些基于Web的工具也许根本不会提供动态自动换行功能。一些团队更喜欢较长的单行代码。如果某个团队对单行代码长度的问题达成了共识，并且由该团队专门维护其代码的话，在将文档字符串与注释保持在72个字符以内的前提下，将名义上的单行代码的最大长度从80个字符提升到100个也是可以的（有效的将实际字符最大长度提高到了99个）。Python标准库是保守的，选择了将单行代码长度限制在79个字符以内（文档字符串/注释72个字符以内）。最为推荐的长行换行方式是在圆括号、方括号、花括号内的Python隐式行续6)。