《改善Python程序的91个建议》阅读笔记

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

注释："""块注释"""、#行注释、文档注释（docstring）

1.对复杂的操作，算法，难理解的技巧进行注释；

2.注释和代码隔开，块注释后留白，保证良好的阅读性；

3.对外部可访问的函数和方法添加文档注释：描述方法的功能，说明参数，返回值和可能发生的异常；

函数注释示例：

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

4.文件头中包含copyright申明，模块描述，以及作者信息及变更记录；

文件头示例：

"""
    Licensed Materials - Property of CorpA
    (C) Copyright A Corp. 2010, 2016 All Rights Reserved
    Copyright statement and purpose...
---------------------------------------------------------------
File Name    : one.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.使用注释利于他人的阅读理解，也利于自己快速理解旧代码的编写思路；

6.注释用于解释代码的功能，原因，想法；

7.将无用的代码直接删除而非注释掉；

8.注释简洁清晰，及时更新。

建议16：分清 == 与is的适用场景

1.is表示对象标示符（object identity），仅当比较的对象是同一个对象返回True,在内存中分配的是同一内存空间，相当于id(a) == id(b)；

2. ==  表示相等（equal），检验两对象的值相等。

参考书籍：

《编写高质量代码改善Python程序的91个建议》