Python学习笔记--变量与注释

近期阅读朱雷（@piglei）所著《Python工匠》一书，颇有收获，特对书中每章节的总结部分内容进行摘录，供自己未来进一步学习。

在一段代码里，变量和注释是最接近自然语言的东西。因此，好的变量名，简明扼要的注释可以显著提升代码的质量。在给变量起名时，尽量使用描述性强的名字，但也得注意别过了头。

以下是“变量与注释”章节的要点知识总结：

1、变量和注释决定“第一印象”：

a>变量和注释是代码里最接近自然语言的东西，它们的可读性非常重要

b>即使是实现同一个算法，变量和注释不一样，给人的感觉也会截然不同

2、基础知识：

a>Python的变量赋值语法非常灵活，可以使用*variables 型号表达式灵活赋值

b>编写注释的两个要点：不要用来屏蔽代码，而是用来解释“为什么”

c>接口注释是为使用者而写，因此应该简明扼要地描述函数职责，而不必描述函数包含太多函数实现的内部细节

d>可以用Sphinx格式文档或类型注释给变量表明类型

3、变量名字很重要

a>给变量起名要遵循PEP8原则，代码的其它部分也同样如此

b>尽量给变量其描述性强的名字，但评价描述性也需要结合场景

c>在保证描述性的前提下，变量名要尽量短

d>变量名要匹配它所表达的类型

e>可以使用一两个字符的超短名字，但注意不要过度使用

f>同一段代码内，不要出现多个相识的变量名，比如同时使用users、user1、user2这种序列

4、代码的组织技巧

a>按照代码的职责来组织代码：让变量定义靠近使用

b>适当定义临时变量可以提升代码的可读性

c>不必要的标量会让代码显得冗长、啰嗦

d>同一个作用域内不要有太多变量，解决办法：提炼数据类、拆分函数

e>空行也是一种特殊的“注释”，适当的空行可以让代码更易读

5、代码的可维护性技巧

a>保持变量在两个方面的一致性：名字一致性与类型一致性

b>显示优于隐式：不要使用locals()批量获取变量

c>把接口注释当成一种函数设计工具：先写注释，后写代码

关于注释

a>代码注释：Python注释主要有2种，一种是最常见的代码内注释，通过在行首输入#号来表示，当注释包含多行内容时，同样使用#号：

# 用户输入可能会有空格，使用strip()去掉空格
username = extract_username(input_string.strip())

# 使用strip()去掉空格的好处：
# 1. 数据库保存时占用空间更小
# 2. 不必因为用户多打了一个空格而要求用户重新输入
username = extract_username(input_string.strip())

b>接口注释：除使用#号注释外，另外一种注释则是函数（类）文档（docstring），这些文档也称为接口注释（interface comment），这些注释在定义函数（类）名的下一行，使用两个三连的单引号或双引号'''  '''("""  """)，用于解释给调用函数（类）的用户使用，解释功能，及参数说明。

class Person:
    """人
    :param name:姓名
    :param age:年龄
    :param favorite_color:最喜欢的颜色
    """

    def __init__(self.name,age,favorite_color):
        self.name = name
        self.age = age
        self.favorite_color = favorite_color

关于变量(我拟采用)

a>类名：采用驼峰命名法，第一个字母大写，每个单词首字母大写，比如：FooClass

b>函数：采用蛇形命名法，均小写字母，下划线连接，尽量描述，比如bar_function

c>常量：全大写字母，下划线相连，比如MAX_VALUE

d>普通变量：全小写字母，下划线相连，比如min_width

e>如果变量仅内部使用，增加下划线前缀，比如_local_value

f>如果变量名同关键字，增加下划线后缀，比如class_

几个知识点：

a>单下划线变量名 _

在常用的诸多变量名中，单下划线 _ 是一个比较特殊的一个。它常作为一个无意义的占位符出现在赋值语句语句中。_这个名字本身没有什么特别之处，算是约定俗成的一种用法。

比如在解包赋值时忽略某些变量，就可以使用 _ 作为变量名：

# 忽略展开时的第二个变量
author,_ = usernames

# 忽略第一个和最后一个变量之间的所有变量
username,*_,score = data

在Python交互命令行（直接执行Python命令进入的交互环境）里，_ 变量还有一个特殊的含义——默认保存我们输入的上个表达式的返回值。

b>给变量注明类型

Python是动态类型语言，使用变量时不需要做任何类型声明。这是优势，让编程变得简单，但可读性就出现打折。为了解决动态类型带来的可读性问题，最常见办法就是在函数文档（docstring）里做文章，可以把每个函数参数的类型与说明全都写到函数文档里。Python推荐如下：

def remove_invalid(items):
    """剔除items里面无效的元素
    
    :param items:待剔除的对象
    :type items：包含整数的列表,[int,...]
    """

在上面代码的函数文档中，使用type items：注明了items是个整数型列表。

在Python3.5版本之后，可以使用类型注解功能来直接注明变量类型，是Python内置功能，越来越流行如此使用。案例如下：

from typing import List

def remove_invalid(items:List[int]):
    """剔除items里面无效的元素
    
    :param items:待剔除的对象
    """
    ......
    

List 表示参数为列表类型，[int]表示里面的成员是整数。

需要注意：“类型注解”只是一种有关类型的注释，系统并不提供任何校验功能。

c>匹配布尔型变量名一个原则：一定要让读到变量的人觉得它只是“肯定”和“否定”两种可能。一般可以采用is、has、allow这些非黑即白的此装饰，比如：

is_superuser :是否是超级用户，是/不是

has_errors ：有没有错误，有/没有

allow_empth ：是否允许为空值，允许/不允许

d>匹配int/float类型的变量名：当人们看到和数字有关的名字时，能够自然会认定是int或者float类型，比如：

释义为数字的所有单词：port(端口号）、age(年龄）、radius(半径）等；

使用以_id结尾的单词：比如user_id、host_id;

使用length/count开头或者结尾的单词：lenght_of_username、max_length、user_count

最好别使用一个名称的复数形式作为int类型的变量名，比如apples、trips等，因为这些名字容易和哪些装着Apple和Trip的普通容器对象（列表）混淆，建议使用number_of_apples或trips_count这类复合词来作为int类型的名。