改善python程序的91个建议读书笔记(2)

建议4:在代码中适当添加注释

python中有3种形式的代码注释:块注释,行注释以及文档注释(docstring).这三种形式的惯用法大概有如下几种:
1.使用块或者行注释的时候仅仅注释那些复杂的操作,算法.还有可能别人难以理解的技巧或者不够一目了然的代码.
2.注释和代码隔开一定的距离,同时在块注释之后最好多留几行空白再写代码.下面两行的代码显然第一行的阅读性要好.

x = x+1     # increase x by 1
x = x+1 # increase by 1

docstring推荐的函数注释如下:
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.
            #such as strqueue:string,string queue list for search.
            parameter2: parameter type, what is this parameter used for.
            #such as str:string,string to find
    Returns:
            return type, return value.
            #such as boolean,sepcial string found return True,else return False
    """
        function body
        ...
        ... 

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

    Licensed Materials - Property of CorpA
    File name: comments.py
    Description:description what the main function of this file
    Author:Author name
    Change Activity:
            list the change activity and time and author information.

建议5.通过适当添加空行使代码布局更加优雅,合理

在一组代码表达完一个完成的思路之后,应该使用空白航进行分隔.
如在每个函数之间,导入声明,变量赋值等.

尽量保持上下文语义的易理解性.如果一个函数需要调用另一个函数的时候,尽量把他们放在一起,最好调用者在上,被调用者在下.

避免过长的代码行,每行最好不要超过80个字符.

不要为了保持水平对齐而使用多余的空格.

同时不要在一行有多个命令,不要将X=1;y=2直接写到一行中.

建议6.编写函数的4个原则

原则1:函数设计要尽量短小.嵌套层次不宜过深.不需要上下拉动滚动条就能获得整体感观,而不是来回翻动屏幕去寻找某个变量或者某条逻辑判断.最好控制在3层以内.

原则2:函数声明应该做到合理,简单,易于使用.除了函数名能正确反映其大体功能外,参数的设计也应该简洁明了,参数个数不宜太多.

原则3:函数参数设计应该考虑向下兼容.随着需求的变更和版本的升级,前一个版本中设计的函数可能需要进行一定的修改才能满足这个版本的要求.例如新增加日志处理,会导致程序中函数调用的接口发生改变.更好的方法是通过加入默认参数来避免这种退化,做到向下兼容.

def readfile(filename,logger=logger.info):

原则4:一个函数只做一件事,尽量保证函数语句粒度的一致性.所有的语句尽量在一个粒度上.

Python中函数设计的好习惯还包括:不要在函数中定义可变对象作为默认值,使用异常替换返回错误,保证通过单元测试.