Google开源项目风格指南之　Python（二）

概要

文件和sockets，todo注释，导入格式，语句，访问控制，命名，Main

内容

文件和sockets

在文件和sockets结束时候，显示的关闭它 除了文件之外，sockets或其他类似文件的对象在没有必要的情况下打开，会有很多副作用： １可能会消耗有限的系统资源，如文件描述符，如果这些资源在使用后没有及时归还系统，用于处理这些对象的代码会将资源消耗殆尽 ２持有文件将会阻止文件的其他操作，比如移动删除之类 ３仅仅从逻辑上关闭文件和sockets，它们仍然可能会被共享的程序进行读写操作 幻想当文件对象析构时, 文件和sockets会自动关闭, 试图将文件对象的生命周期和文件的状态绑定在一起的想法, 都是不现实的. 因为有如下原因: １没有任何方法可以确保运行环境会真正的执行文件的析构. 不同的Python实现采用不同的内存管理技术, 比如延时垃圾处理机制. 延时垃圾处理机制可能会导致对象生命周期被任意无限制的延长. ２对于文件意外的引用,会导致对于文件的持有时间超出预期(比如对于异常的跟踪, 包含有全局变量等).

使用with语句管理文件：

with open("hello.txt") as hello_file:
    for line in hello_file:
        print line

对于不支持with语句的类似文件的对象，使用contextlib.closing():

import contextlib

with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
    for line in front_page:
        print line

TODO注释

为临时代码使用todo注释，是一种短期解决方案 TODO注释应该在所有开头处包含”TODO”字符串, 紧跟着是用括号括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么. 主要目的是为了有一个统一的TODO格式, 这样添加注释的人就可以搜索到(并可以按需提供更多细节). 写了TODO注释并不保证写的人会亲自解决问题. 当你写了一个TODO, 请注上你的名字. 如果你的TODO是”将来做某事”的形式, 那么请确保你包含了一个指定的日期(“2009年11月解决”)或者一个特定的事件(“等到所有的客户都可以处理XML请求就移除这些代码”).
# TODO(kl@gmail.com): Use a "*" here for string repetition.
# TODO(Zeke) Change this to use relations.

导入格式

每个导入应该独占一行 导入总应该放在文件顶部, 位于模块注释和文档字符串之后, 模块全局变量和常量之前. 导入应该按照从最通用到最不通用的顺序分组: 1标准库导入 2第三方库导入 3应用程序指定导入 每种分组中, 应该根据每个模块的完整包路径按字典序排序, 忽略大小写

语句

通常每个语句应该独占一行 不过, 如果测试结果与测试语句在一行放得下, 你也可以将它们放在同一行 如果是if语句, 只有在没有else时才能这样做. 特别地, 绝不要对 try/except这样做, 因为try和except不能放在同一行.

访问控制

在python中，对于琐碎的不太重要的访问函数，使用公有变量来取代它们 这样可以避免额外的函数调用开销， 当增加更多功能时候，可以用属性property来保持语法的一致性 另一方面，如果访问更复杂，或者变量的访问开销很显著．那么你应该使用像 get_foo()和set_foo()这样的函数调用，如果之前的代码行为允许通过属性访问，那么 就不要将新的访问函数和属性绑定，这样，任何试图通过老方法访问变量的代码就没法运行，使用者也就意识到复杂性发生了变化

命名

module_name package_name ClassName method_name ExceptionName 
function_name GLOBAL_VAR_NAME instance_var_name
function_parameter_name  local_var_name

应该避免的名称 单字符名称，除了计数器和迭代器 包／模块名中的连字符－ 双下划线开头并结尾的名称（python保留，例如__init__）
命名约定： １所谓内部internal表示仅模块内可用，或者，在类内是保护或者私有的 2 用单下划线开头表示模块变量或函数是protected的（使用import * from 时候不会包含） ３用下划线__开头的实例变量或方法表示类内私有 ４将相关的类和顶级函数放在同一个模块中 ５对类名使用大写字母开头的单词 模块名应该用小写加下划线的方式，
python之父Guido推荐的规范

Type	Public	Internal
Modules	lower_with_under	_lower_with_under
Packages	lower_with_under
Classes	CapWords	_CapWords
Exceptions	CapWords
Functions	lower_with_under()	_lower_with_under()
Global/Class Constants	CAPS_WITH_UNDER	_CAPS_WITH_UNDER
Global/Class Variables	lower_with_under	_lower_with_under
Instance Variables	lower_with_under	_lower_with_under (protected) or __lower_with_under (private)
Method Names	lower_with_under()	_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters/Class Variables	lower_with_under
Local Variables	lower_with_under

推荐风格.png

Main

即使是一个打算被当作脚本的文件，也应该是可以导入的，并且简单的导入不应该导致这个脚本的主功能main functionality被执行，这是一种副作用，主功能应该放在一个main()函数中 在Python中, pydoc以及单元测试要求模块必须是可导入的. 你的代码应该在执行主程序前总是检查if __name__ == '__main__', 这样当模块被导入时主程序就不会被执行. 所有的顶级代码在模块导入时都会被执行. 要小心不要去调用函数, 创建对象, 或者执行那些不应该在使用pydoc时执行的操作.

引用
Google开源项目风格指南