Python 进阶 01- 变量和注释的使用

变量和注释使用

变量解包

python 中可以对变量进行解构

python
usernames = ['silon', 'sibine']

user_a, user_b = usernames

python
# 可以对嵌套解构进行解构

attrs = [1, [66, 77]]

num1, (num2, num3) = attrs

同时可以对被解构的内容进行切片

python
data = [1, 2, 3, 4, 5]

# 动态解构和切片赋值效果相同
a, *b, c = data

# 切片赋值
a, b, c = data[0], data[1:-1], data[-1]

变量类型注释

python 在 3.5 版本之后，提供了类型注释

类型注释用于标明变量的类型

需要注意的是：
类型注释只是一种注释，不提供任何校验功能，如果需要校验类型，可以安装其他静态类型检查工具（mypy 等）

使用类型注释，可以配合 ide，得到更好的代码提示效果

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

另外官方也推荐使用 sphnix 格式的注释


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

变量命名规范

Python制定了官方的编码风格指南：PEP 8。这份风格指南里有许多详细的风格建议，比如应该用4个空格缩进，每行不超过79个字符，等等。其中，当然也包含变量的命名规范：

· 对于普通变量，使用蛇形命名法，比如max_value；
· 对于常量，采用全大写字母，使用下划线连接，比如MAX_VALUE；
· 如果变量标记为“仅内部使用”，为其增加下划线前缀，比如_local_var；
· 当名字与Python关键字冲突时，在变量末尾追加下划线，比如class_。

除了必须要遵守 pep8 标准，还需要保证以下要求，达到好的效果

描述性要强
要使用尽量精确的词语进行变量描述，避免使用 data、temp 等非常泛性的名称，容易与其他变量混淆
长度尽量短
可以结合上下文，进行变量名称的精简，例如可以把how_many_points_needed_for_user_level3直接删减成level3_points
匹配类型使用固定的命名格式，来表达该变量的类型常见组合例如：

类型组合
bool is_super、 has_permission 、 allow_empty
int和float port、 age、 _cnt 、 _length
list 复数变量名: apples
其他建议使用类型注释

注意不要使用复数格式，用于 int 类型变量
仅特定场景使用短命名

场景命名
数组索引 i,j,k
某个整数 n
某字符串 s
某异常 e
文件对象 fp
同一段代码，不要出现多个相似变量，例如 name1，name2

类型	组合
bool	is_super、 has_permission 、 allow_empty
int和float	port、 age、 _cnt 、 _length
list	复数变量名: apples
其他	建议使用类型注释

场景	命名
数组索引	i,j,k
某个整数	n
某字符串	s
某异常	e
文件对象	fp

注释使用规范

编写代码时，使用注释，有几个注意点

不建议将注释作为临时屏蔽代码的工具
不要觉得注释掉的内容以后还要用，如果需要，可以从git 历史中寻找

不要使用注释复述代码
注释作为代码之外的说明性文字，应该尽量提供那些读者无法从代码里读出来的信息。描述代码为什么要这么做，而不是简单复述代码本身。
错误示范：

python
#调用strip()去掉空格
input_string = input_string.strip(

正确示范：

python
#如果直接把带空格的输入传递到后端处理，可能会造成后端服务崩溃
# 因此使用strip() 去掉首尾空格
input_string = input_string.strip(

适当增加指引式注释
指引性注释的主要作用是降低代码的认知成本，让我们能更容易理解代码的意图。

python
#初始化访问服务的client对象
token = token_service.get_token()
service_client = ServiceClient(token=token)
service_client.ready()
# 调用服务获取数据，然后进行过滤
data = service_client.fetch_full_data()
for item in data:
    if item.value > SOME_VALUE:
    ...

同时使用指引式注释，也能帮助自己梳理代码

python
service_client = make_client()
data = fetch_and_filter(service_client)

不要过度注释使用者不需了解的内容，例如编写代码的思路

变量使用的建议

要保证变量的一致性
- 名字一致性：不要把同一个事务，在一个系统里各处起不同的名称
  例如 user_avatar_url, user_profile_url
- 类型一致性：不要把同一个变量重复指向不同类型的值，应该创建新的变量来处理新的类型的值
```
python
def foo():
users = {'data': ['piglei', 'raymond']}
...
# 使用一个新名字
user_list = []
...
```

变量的定义尽量靠近
不要一次性都在顶部把局部变量定义好，应该在即将使用到该临时变量时，再定义
好的例子如下

python
def generate_trip_png(trip):
"""
根据旅途数据生成 PNG 图片
"""
# 开始初始化 waypoints 数据
waypoints = []
waypoints.append(...)
...
# 开始处理 photo_markers、text_markers
photo_markers, text_markers = [], []
photo_markers.append(...)
...
# 开始计算 marker_count
marker_count = 0
marker_count += ..

为复杂处理，创建临时变量，提升可读性
最常见的就是，将复杂的条件判断，进行 flag 的赋值

python
#为所有性别为女或者级别大于3的活跃用户发放10000个金币
user_is_eligible = user.is_active and (user.sex == 'female' or user.level > 3)
if user_is_eligible:
    user.add_coins(10000)

同一作用域不要使用过多变量
要减少函数里的变量数量，最直接的方式是给这些变量分组，建立新的模型（数据类）

能不定义变量，就不定义
不需要过度优化，不必为了那些未来可能出现的变动，牺牲代码此时此刻的可读性。如果以后需要定义变量，那就以后再做

python
def get_best_trip_by_user_id(user_id):
    # 心理活动：嗯，这个值未来说不定会修改/二次使用，我们先把它定义成变量吧！
    user = get_user(user_id)
    trip = get_best_trip(user_id)
    result = {
        'user': user,
        'trip': trip
    }
    return result

正确示例：

python
def get_best_trip_by_user_id(user_id):
    return {
        'user': get_user(user_id),
        'trip': get_best_trip(user_id)
    }

不要使用 locals()
locals()是Python的一个内置函数，调用它会返回当前作用域中的所有局部变量
其他人在阅读代码时，为了搞明白模板渲染到底用了哪些变量，必须记住当前作用域里的所有变量
使用locals()还有一个缺点，那就是它会把一些并没有真正使用的变量也一并暴露

注释使用建议

适当使用空行区分代码块
尽量先写注释后写代码