编写高质量代码--改善python程序的建议（一）

原文发表在我的博客主页，转载请注明出处！

初衷

python是一个入门十分容易的编程语言，但是想要写好python却是一件不容易的事情，如果不是专业使用python的人，只是将python作为一个脚本语言或者用来处理数据，到了掌握基本的语法之后，便不再寻求进步。但是相信每个学习python的人都知道pythonic这个单词，这个词语很难定义，全靠心领神会，但大家心中都认同Tim Peters的《The Zen of Python》中提到的几点：

• 美胜丑，显胜隐，简胜杂，杂胜乱，平胜陡，疏胜密
• 找到简单问题的一个方法，最好是唯一的方法
• 难以解释的实现，源自不好的主意

使用python已经很久了，发现自己处在了一个上升的瓶颈，而我坚信读书是解决这种问题的不二法门，所以写一些读书笔记，当然书中的有些内容我不敢苟同，所以也会加入自己的甄别和想法。

---

建议一：写pythonic代码

• 代码风格
  举几个常见的例子，相信大家就会理解
  两个变量交换:

a, b = b, a

遍历容器：

for i in container:
    do_sth_with(i)

安全的处理文件：

with open(path,"r") as f:
    do_sth_with(f)

• 标准库
  写pythonic需要对标准库有充分的理解，特别是内置函数和内置数据类型，比如，对于字符串格式化，一般写作这样：

print 'Hello %s!' % ('Tom',)

这样非常影响可读性，数量多了之后，很难清楚哪一个占位符对应哪一个参数，所以最好这样写：

print 'Hello %(name)s!' % {'name':'Tom'}

这样其实已经相当pythonic，但是想想%占位符，其实是从学习C语言的时候就深深扎根头脑了，在python中，还有更加pythonic的写法。

print '{greet} from {language}.'.format(greet = 'Hello world', language = 'Python')

其中str.format()非常清晰的表明了语句的意图，称为python最为推荐的字符串格式化方法。

• pythonic的库或者框架
  包和模块的命令采用小写、单数形式，而且短小。
  包通常仅作为命名空间，如只包含空的__init__.py文件。

---

建议二：理解python和C语言的不同之处

• “缩进”与“｛｝”
• '与"
• 三元操作符 “?:”

python:  X if X<Y else Y
C:  X<Y:X:Y

• swith...case

上述的区别相信使用过python的人都清楚，所以不再赘述

---

建议三：在代码中适当添加注释
python中有三种形式的代码注释：块注释、行注释以及文档注释

• 使用块注释或者行注释的时候仅仅注释哪些复杂的操作、算法，或者难以理解，不能一目了然的代码
• 给外部可访问的函数和方法（无论简单与否）添加文档注释。注释要清楚的描述方法的功能，并对参数、返回值以及可能发生的异常进行说明，使得外部调用它的人员仅仅看文档注释就能正确使用。较为复杂的内部方法也需要进行注释。推荐的函数注释如下：

def FuncName(parameter1, parameter2):
    """
	Describe what this function does:
	 #such as "Find whether the special string is in the queue or not"
	Args:
		parameter1:parameter type, what is this parameter used for
		parameter2:parameter type, what is this parameter used for
	Returns:
		return type, return value
    """
		function body
		···
		···

• 头文件中包含copyright申明、模块描述等，如有必要，可以考虑加入作者信息以及变更记录。

"""
	Licensed Materials - Property of CorpA
	(C) Copyright A Corp. 1999, 2011 All Rights Reserved
	Copyright statement and purpose... 
--------------------------------------------------------
File name   :
Description :

Author:
Change Activity:
--------------------------------------------------------
"""

---

建议四：通过适当添加空行使代码布局更为优雅、合理

• 在一组代码表达完一个完整的思想后，应该用空白行进行间隔。如每个函数之间，导入声明、变量赋值等。推荐在函数定义或者类定义之间空两行，在类定义与第一个方法之间，或者需要进行语义分割的地方空一行。
• 尽量保持上下文语义的易理解性，如当一个函数需要调用另一个函数的时候，尽量将他们放在一起，最好调用者在上，被调用者在下。
• 避免过长的代码行，每行最好不要超过80个字符。
• 空格的使用要能够在需要强调的时候警示读着，在疏松关系的实体间起到分隔作用，而在具有紧密关系的时候不要使用空格，具体如下：

1. 二元运算符（赋值（=），比较（==，<, >, !=, <>, <=, >=, in, not in, is, is not），布尔运算（and, or, not））的左右两边应该有空格
2. 逗号和分号前不要使用空格
3. 函数名和左括号之间、序列索引操作时序列名和[]之间不需要空格，函数的默认参数两侧不需要空格
4. 强调前面的操作符的时候使用空格。

---

建议五：编写函数的4个原则*

• 函数设计要尽量短小
• 函数声明要做到合理、简单、易于使用
• 函数参数设计应该考虑向下兼容
• 一个函数只做一件事情，尽量保证函数语句粒度的一致性

---

建议六：将常量集中到一个文件
在python中如何使用常量呢，一般来说有一下两种方式：

• 通过命名风格来提醒使用者该变量代表的意义为常量。如TOTAL，MAX_OVERFLOW，然而这种方式并没有实现真正的常量，其对应的值仍然可以改变，这只是一种约定俗成的风格
• 通过自定义的类实现常量功能，这要求符合“命名全部为大写”和“值一旦绑定便不可再修改”这两个条件。可以通过异常来解决这个问题

class _const:
	class ConstError(TypeError): pass
	class ConstCaseError(ConstError): pass
	
	def __setattr__(self, name, value):
		if self.__dict__.has_key(name):
			raise self.ConstError, "Can't change const. %s" %name
		if not name.isupper():
			raise self.ConstCaseError, 
				'const name "%s" is not all uppercase' %name
		self.__dict__[name] = value

import sys
sys.modules[__name__] = _const()

上面定义了一个类用于约束常量定义，定义常量方式如下（建议将所有的常量定义在一个文件constant.py中）：

import const
const.COMPANY = "IBM"
...

当在其他模块中引用这些常量时，按照如下方式进行即可：

from constant import const
print const.COMPANY

---

总结：本篇博客主要列举了一些常见的编程准则，而其中列举的一些建议不光可以用在python，在其他编程语言中同样适用。

参考：编写高质量代码--改善python程序的91个建议