Python变量命名规范与注释最佳实践详解
本文深入解析Python变量与注释的高级用法。涵盖变量解包的多种语法场景，详解类型注解的提示作用及常见命名约定。重点阐述PEP8规范下的变量命名原则，包括蛇形命名、常量定义及描述性要求。同时分析注释的正确使用方式，区分解释性与指引性注释，并指出屏蔽代码、复述代码等常见错误用法，帮助提升代码可读性与维护性。
Python变量与注释的高级用法解析
1. 概述
优秀的变量命名与注释设计并非为了迎合计算机，而是服务于每一位阅读代码的人。变量与注释是传达开发者意图的核心载体，对提升代码整体质量具有不可替代的作用。
2. 变量
2.1. 变量解包
1. 什么是变量解包
变量解包是指将一个可迭代对象中的所有成员一次性赋值给多个变量的过程。
2. 变量解包语法
# 变量解包
username = ['zhangsan', '18']
name, age = username
print('name:{}, age:{} '.format(name, age))
# 嵌套类型变量解包
username = [1, ['zhangsan', 18]]
number, (name, age) = username
print('number:{}, name:{}, age:{}'.format(number, name, age))
# 匹配模式解包
data = ['zhangsan', 'banana', 'apple', 'orange', 18]
name, *fruits, score = data
print('name:{}, fruits:{}, score:{}'.format(name, fruits, score))
# 切片解包
data = ['zhangsan', 'banana', 'apple', 'orange', 18]
name, fruits, score = data[0], data[1:-1], data[-1]
print('name:{}, fruits:{}, score:{}'.format(name, fruits, score))
# 变量解包用到for循环
for name, age in [('zhangsan', 15), ('lisi', 18)]:
print('name:{}, age:{}'.format(name, age))
# 单下划线变量名
username = ['zhangsan', 19]
name, _ = username
print(name, _)
2.2. 为变量注明类型
1. 变量注明类型介绍
Python中的变量类型注解与Java等语言不同，它仅作为一种提示功能，并不提供强制的类型校验。因此，即使传入的变量类型与注解类型不一致，代码也不会报错。
变量注明类型的语法十分简洁，只需在变量名后使用冒号分隔并指定类型即可。
2. 变量注明类型示例
# list表示参数为列表类型，int表示里面的成员是整形
def remove_invalid(item: list[int]):
print(item)
# 传入符合变量类型参数
remove_invalid([1, 2, 3])
# 传入不符合变量类型参数，不影响函数执行结果。
remove_invalid(1)
# 类型注解使用demo
class Duck:
def __init__(self, color:str):
self.color = color
# 为quack方法注明返回值类型为None
def quack(self) -> None:
print(f"Hi, I'm a {self.color} duck")
# -> List[Duck]：用typing模块的List对象为函数返回值标注具体类型
def create_random_ducks(number:int) -> List[Duck]:
# 为变量加上类型声明
ducks: List[Duck] = []
for _ in number:
color = random.choice(['yellow', 'white', 'gray'])
ducks.append(Duck(color=color))
return ducks
ducks = create_random_ducks((1,2,3))
for duck in ducks:
duck.quack()2.3. 变量命名原则
变量命名主要遵循两种流派：一是通过大小写区分单词的驼峰命名法，如Java语言；二是通过下划线连接的蛇形命名法，如Python语言。
- 遵循PEP8原则
- 描述性要强
- 长度尽量短
- 变量注明类型
- 超短命名
1. 遵循PEP8原则
PEP8全称为《Python Enhancement Proposal #8》，即《8号Python增强规范》，它为代码编写风格提供了权威指南。在变量命名方面，具体规范如下。
- 普通变量应采用蛇形命名法，例如 max_value。
- 常量应采用全大写字母，并使用下划线连接，例如 MAX_VALUE。
- 仅内部使用的变量，应在变量名前增加下划线前缀，例如 _local_var。
- 当变量名称与Python关键字冲突时，应在变量末尾追加下划线，例如 class_。
2. 描述性要强
写作过程中，斟酌恰当的词语至关重要，不同词语的描述性强弱各异。例如，“冬天傲骨的梅花”比“花”具有更强的描述性。变量命名同理，描述性强的变量名能显著提升代码的可读性。
# 描述性弱的变量名称:看不出它在描述什么 vlaue = process(s.strip()) # 描述性强的变量名称：从用户输入参数中解析出用户名称，并剔除参数中的空格。 username = extract_username(input_string.strip())
3. 长度尽量短
如果一个变量名特别长且频繁出现，读者不会觉得它精确，反而会觉得啰嗦难读。在保证描述清晰的前提下，应尽量让名字简短易读，通常控制在4个单词以内。
4. 变量注明类型
虽然Python不需要显式声明变量类型，但为了提升可读性，建议为变量注明类型。此外，还有约定俗成的变量名称与类型的匹配关系，以下是一些常见的匹配示例。
| 变量名 | 含义 | 说明 |
|---|---|---|
| is_superuser | 是否是超级用户 | is 表示是或不是 |
| has_errors | 有没有错 | hans 表示有或没有 |
| allow_empty | 是否允许空值 | allow表示是否允许 |
5. 超短命名
在变量命名中，有一类名称较为特殊，仅由一两个字母组成。它们通常分为两类：一类是大家约定俗成的短名字，另一类是起别名。
约定俗成的常用名称
- 数组索引三剑客：i、j、k
- 某个整数：n
- 某个字符串：s
- 某个异常：e
- 文件对象：fp
长名称起别名
is_not_normal as l
3. 注释
注释不会影响代码的实际行为，但它会显著影响代码的可读性。
3.1. 注释类型
Python的注释主要分为两种：一种是代码内注释，另一种是函数或类的注释，也称为接口注释。
行内注释
# 使用strip()去掉空格的好处： # 1.数据库保存数据时占用空间更小 # 2.不必因为用户多打了空格而要求用户重新输入。 username = extract_username(input_string.strip())
接口注释
class Person: # 使用三个单引号或三个双引号就是接口注释。 '''人 ：param name: 姓名 : param age: 年龄 : param favrite_color: 最喜欢的颜色 ''' def __init__(self, name, age, favrite_color): self.name = name self.age = age self.favrite_color = color
3.2. 错误使用注释案例
1. 用注释屏蔽代码
在编程中，有时会使用注释来屏蔽代码。如果这些代码不再需要，应直接删除；如果需要，可以从Git仓库中找回。临时注释掉的大段代码对阅读者而言是一种干扰，没有任何实际意义。
2. 用注释复述代码
# 调用strip()去掉空格 input_string = input_string.strip()
上述注释完全是冗余的，因为读者从代码本身就能读取到注释中的信息。优秀的注释应当如下所示。
# 如果将带有空格的参数传递到后端处理，可能会造成服务奔溃 # 因此使用strip()去掉收尾空格 input_string = input_string.strip()
注释作为代码之外的说明性文字，应尽可能提供那些读者无法从代码中直接获取的信息，重点描述代码“为什么要这么做”，而不是简单复述代码本身。
除了提供解释性信息的注释外，还有一种常见的注释类型：指引性注释。这种注释不复述代码细节，而是简明扼要地概括代码功能，起到“代码导读”的作用。指引性注释并不提供代码中读不到的新信息——假如没有注释，耐心读完所有代码也能知道其功能。指引性注释旨在降低代码的认知成本，让我们更容易理解代码的意图。
指引性注释示例
# 初始化访问服务的client对象 token = token_service.get_token() service_client = ServiceClient(token = token) service_client.ready()
3. 弄错接口注释的受众
到此这篇关于Python变量与注释高级用法的文章就介绍到这了，更多相关Python变量与注释内容请搜索本站以前的文章或继续浏览下面的相关文章，希望大家以后多多支持本站！
免责声明：本文内容仅供参考，不代表本站观点。转载或引用请注明出处。
