Python工匠 第1章 变量与注释

好的变量与注释并非为计算机而写，而是为每个阅读代码的人而写。变量与注释是作者表达思想的基础，是读者理解代码的第一道门，它们对代码质量的贡献毋庸置疑。

1.1 基础知识

1.1.1 变量常用方法

author = 'piglei'
print('Hello, {}!'.format(author))

author, reader = 'piglei', 'raymond'
author, reader = reader, author

1. 变量解包
   是一种特殊赋值操作，把一个可迭代对象的所有成员，一次性赋值给多个变量。

   usernames = ['piglei', 'raymond']
   author, reader = usernames
   
   attrs = [1, ['piglei', 100]]
   user_id, (username, score) = attrs

   动态解包
   用星号表达式(*variables)作为变量名，可以贪婪地捕获多个值对象，并将捕获的内容作为列表赋值给该表达式。

   data = ['piglei', 'apple', 'orange', 'banana', 100]
   username, *fruits, score = data
   
   # 等价于如下切片语句
   username, *fruits, score = data[0], data[1:-1], data[-1]
   
   # 解包操作可用于循环语句
   for username, score in [('piglei', 100), ('raymand', 90)]:
       print(username)

2. 单下划线变量名_
   通常作为无意义的占位符出现在赋值语句中
   约定俗成：

   # 忽略展开时的第二个变量
   author, _ = usernames
   
   # 忽略第一个和最后一个变量之间的所有变量
   username, *_, score = data

   Python交互式命令行里，_变量特殊含义为：默认保存输入的上个表达式的返回值。

   1.1.2 给变量注明类型

3. 函数文档：Sphinx格式文档

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

4. 类型注解

   from typing import list
   
   def remove_invalid(items: List[int]):
       """ 剔除 items 里面无效的元素 """

   List 表示参数为列表类型，[int] 表示里面的成员是整型。
   类型注解 只是一种有关类型的注释，不提供任何校验功能。需要使用 mypy 等静态类型检查工具检查。
   jira库大量使用了这种注解方式，参考client.py如下函数：

       def project(self, id: str, expand: Optional[str] = None) -> Project:
           """Get a project Resource from the server.
   
           Args:
               id (str): ID or key of the project to get
               expand (Optional[str]): extra information to fetch for the project
                                       such as projectKeys and description.
   
           Returns:
               Project
           """
           return self._find_for_resource(Project, id, expand=expand)

1.1.3 变量命名原则

计算机科学领域只有两件难事：缓存失效和命名。--- Phil Karlton

1. 遵循 PEP 8 原则
2. 描述性要强
3. 尽量短
   尽量不要超过4个单词
4. 匹配类型
   最好别拿一个名词的复数形式来做为 int 类型的变量名，比如 apples、trips 等。因为这类名字容易与那些装着 Apple 和 Trip 的普通容器对象 (List[Apple]、List[Trip]) 混淆。
5. 超短命名

1.1.4 注释基础知识

1. 代码内注释
2. 接口注释
   Sphinx 文档风格
   Google 风格

编写注释常见的3种错误：

1. 用注释屏蔽代码
2. 用注释复述代码
   解释性注释
   指引性注释，降低代码的认知成本

3. 弄错接口注释的受众

   1.2 案例故事

   1.3 编程建议

   1.3.1 保持变量的一致性

   1.3.2 变量定义尽量靠近使用

   1.3.3 定义临时变量提升可读性

   1.3.4 同一作用域内不要有太多变量

   1.3.5 能不定义变量就别定义

   未来没有来，就不需要为未来筹备。

   1.3.6 不要使用locals()

   该内置函数返回当前作用域中的所有局部变量。

   Explicit is better than implicit.
   Python之禅：显示优于隐式。

   1.3.7 空行也是一种注释

   1.3.8 先写注释，后写代码

   在写出一句有说服力的接口注释前，别写任何函数代码。

   1.4 总结