如何编写清晰可读的的Python代码

初衷

1. python是一个入门十分容易的编程语言，但是想要写好python却是一件不容易的事情，如果不是专业使用python的人，只是将2. python作为一个脚本语言或者用来处理数据，到了掌握基本的语法之后，便不再寻求进步。但是相信每个学习python的人都知3. 道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!' % ('Jea',)
这样非常影响可读性，数量多了之后，很难清楚哪一个占位符对应哪一个参数，所以最好这样写：

print 'Hello %(name)s!' % {'name':'Jea'}
这样其实已经相当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

C:  X

上述的区别相信使用过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:
xxxxxxxx:

---

"""

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

• 在一组代码表达完一个完整的思想后，应该用空白行进行间隔。如每个函数之间，导入声明、变量赋值等。推荐在函数定义或者类定义之间空两行，在类定义与第一个方法之间，或者需要进行语义分割的地方空一行。
• 尽量保持上下文语义的易理解性，如当一个函数需要调用另一个函数的时候，尽量将他们放在一起，最好调用者在上，被调用者在下。
• 避免过长的代码行，每行最好不要超过80个字符。
• 空格的使用要能够在需要强调的时候警示读着，在疏松关系的实体间起到分隔作用，而在具有紧密关系的时候不要使用空格，具体如下：
• 二元运算符（赋值（=），比较（==，<, >, !=, <>, <=, >=, in, not in, is, is not），布尔运算（and, or, not））的左右两边应该有空格
• 逗号和分号前不要使用空格
• 函数名和左括号之间、序列索引操作时序列名和[]之间不需要空格，函数的默认参数两侧不需要空格
• 强调前面的操作符的时候使用空格。

建议五：编写函数的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