Python基础练习：注释与标识符的规范与避坑指南

我见过太多初学者学Python，第一个星期就开始啃列表、字典、函数，结果一写项目就乱套：变量名叫a、b、c，代码里一句注释都没有，过两周自己都看不懂自己写的什么。最后跑回来问我怎么回事，其实根子不在"知识量不够"，而在最开始的基础没打牢。所以我一直觉得，学编程的前几课，不应该急着去写功能，而应该先搞清楚游戏规则。作为"python基础练习"系列的第一篇，我选了注释和标识符这两个看似最简单的题目，因为它们是代码质量的起点，也是从"会敲代码"走向"会写代码"的第一道门槛。

这一篇，我会把这两块掰开揉碎讲清楚：注释不只是"给代码加说明文字"，它有四种完全不同的写法，各自承担不同的职责；标识符更不只是"起名字"，它藏着Python这门语言对命名的一整套约束和审美。学完之后你会明白，为什么有的代码一跑就报SyntaxError，为什么有的变量名看着就别扭，以及怎么命名才算是"Pythonic"。

1. 为什么第一个练习要从注释和标识符开始

1.1 这两个概念在整个Python学习中的定位

很多人觉得注释和标识符太简单，不值得单独拿一篇出来讲。恰恰相反，它们是之后所有代码的"地基"。你想想看，后面学变量、学函数、学类，哪一样离得开命名？你写的每一行代码都在用标识符，而项目一旦超过几百行，没有任何一个正常人能全靠记忆理解自己当初的思路——这时候注释就是你的外置大脑。

从语言设计角度看，Python本身也是一门非常强调"可读性"的语言。官方文档里有句著名的话：代码的阅读次数远比编写次数多。所以从第一天开始，就必须养成"写给读者"的习惯，而不是"写给机器"的习惯。注释和标识符，恰好就是Readable Code的左右手。

我说得直白一点：如果变量名起得足够清晰，注释的量可以少一半；如果注释写得到位，别人接手你代码时能在十分钟内上手，而不是花三天来"考古"。

1.2 学完之后你该掌握什么

这一篇的目标非常明确，不需要贪多。学完你应当能做到四件事：

• 熟记Python注释的类型：单行注释、多行注释、文档字符串、编码声明；
• 熟练运用标识符命名规则，知道哪些名字合法、哪些不合法、哪些虽然合法但不推荐；
• 理解关键字（保留字）为什么不能作为标识符，知道Python一共有多少个关键字；
• 能按PEP 8的命名规范，为变量、常量、函数、类分别选择合适的命名风格。

这些听起来不难，但等你实际写代码的时候会发现，低级错误比如"变量名打了中文括号"、"用了class当变量名"，几乎每天都在编程社区的提问帖里出现。这篇文章要做的，就是让你在起步阶段把这些雷全部排掉，而不是等到项目写了一半再回头看语法报错。

2. 注释：写给未来的自己和别人的说明书

2.1 Python里的四种注释写法

Python的注释总共有四种典型形式，很多教材只提了前两种，但实际上后两种在工程实践里的使用频率更高，而且有完全不同的语义。

第一种，单行注释，用井号#。

# 计算用户平均得分 average = total_score / user_count

井号后面的内容一直到行尾都算注释，解释器会直接忽略掉。这种注释可以独占一行，也可以跟在代码末尾，像这样：

average = total_score / user_count # 注意：user_count不能为0

我个人建议：跟在代码后面的"行尾注释"不要写太长，简短提示即可。如果内容超过一行，就应该单独起一行，写在代码上方。

第二种，多行注释，用连续的三对引号"""或'''。

""" 这段是给开发者看的说明， 可以写多行， 通常放在一段较复杂逻辑的上方。 """ def calculate_score(total_score, user_count): pass

这里有个容易误解的细节：Python里用三引号包起来的字符串，如果你没有把它赋值给任何变量，它确实会被解释器当作一条"不产生效果"的语句跳过，所以能起到注释的效果。但它本质上仍然是字符串类型，跟真正的#注释在机制上是不一样的。几年前有团队在线上环境踩过坑——某个模块顶部用了三引号"注释"，结果这个字符串被某些框架扫描到，引发了一个诡异的问题。所以我的建议是：多行注释优先用连续多个#，尽量别用三引号，三引号的位置留给文档字符串。

第三种，文档字符串（docstring），用三引号写在模块、函数、类的内部第一行。

def calculate_score(total_score, user_count): """根据总分和人数计算平均分。 参数: total_score: 总分 user_count: 用户人数 返回: 平均分 """ return total_score / user_count

文档字符串和普通注释最大的区别在于：它可以被Python的help()函数、自动生成文档的工具（比如Sphinx、Doxygen）读取。换句话说，docstring是"给工具和开发者共同看的正式文档"，而#注释是"写给开发者看的随手笔记"。这个定位差异很重要，后面会遇到Doxygen风格注释、字段注释（比如数据结构字段的说明），它们的核心思路都是让"注释"变成可提取的结构化信息。

第四种，编码声明注释，写在文件第一行或第二行。

# -*- coding: utf-8 -*-

在Python 3里，源文件默认使用UTF-8编码，所以这个声明绝大多数时候可以省略。但有些老项目、或者说需要支持Python 2的遗留代码里还会见到。你和别人协作时看到这一行，知道它是编码声明即可，不要觉得奇怪，也不要手贱删掉。

2.2 什么时候该写注释，什么时候不该写

有经验的开发者都知道，"注释应该解释为什么，而不是解释是什么"。一行代码在做什么，代码本身就能说清楚；只有代码背后的原因、背景、约束，才需要注释。

我举个例子。下面的注释就是典型的废话：

# 把x加1 x = x + 1

这种注释没有任何信息量，唯一的作用是增加噪音。而下面这段注释才是真正有价值的：

# 这里不能直接用pop(0)，因为需要保留原始列表顺序供后续回溯使用 first_item = items.pop(0)

看到了吗？注释解释的是一个"反直觉的选择"，解释了背后的权衡和小心机。别人读代码时，真正困惑的不是"代码做了什么"，而是"为什么这么做、为什么不用别的做法"。这才是注释存在的意义。

另外一个黄金法则是：当你的代码复杂到必须写注释才能看懂，通常意味着代码本身需要重构。与其写一大段注释来解释一团乱麻，不如把逻辑拆成几个命名清晰的小函数，让代码自己"说话"。好代码加注释是相辅相成，不是互相救火。

2.3 文档字符串（docstring）的特殊地位

既然说到注释，docstring值得单独展开。因为它在Python生态里不是"可选的加分项"，而是非常重要的约定。PEP 257专门规范了docstring的写法，主流IDE也会在你定义函数后自动生成docstring模板。

一个团队项目里，如果每个函数都有docstring，那么很多工具可以直接从源码里提取API文档，根本不需要额外维护一套文档站点。这也是为什么你会看到"字段注释""包注释""doxygen注释"这些热搜词——它们本质上是同一件事的不同实现方式：让注释结构化、可提取、可自动生成文档。

举例来说，如果你写了一个工具模块，里面有个函数用来把金额从分转成元：

def fen_to_yuan(fen: int) -> float: """金额单位转换：分转元。 参数: fen: 金额，单位是分，必须为正整数 返回: 金额，单位是元 示例: >>> fen_to_yuan(100) 1.0 """ return fen / 100

以后任何人调用这个函数，输入help(fen_to_yuan)，就能看到完整的说明。如果函数写得足够多、模块足够完整，用Sphinx可以一键生成漂亮的在线文档。这种"代码即文档"的思路，Python社区非常推崇。

这里再补充一个实操细节：docstring的三引号最好用"""而不是'''，这是PEP 257的建议。另外docstring的结尾三引号建议单独占一行，这样后面如果追加内容，diff记录更清晰，代码审查时看起来也更舒服。

2.4 关于编码声明那点事

编码声明注释（# -*- coding: utf-8 -*-）在Python 3里其实可以完全不写，因为Python 3的默认源码编码就是UTF-8。但我在整理这篇练习时还是把它列出来，是因为你在网上仍会看到大量教程和旧项目里保留着它。

如果跟着老教程读到这一行，你至少要知道：这不是给机器看的强制指令（Python 2时代它确实是），更不是某种"魔法咒语"。它只是一个历史遗留但无害的习惯。真正要注意的是：无论有没有这行注释，源文件本身的编码必须和解释器理解的一致。比如你用记事本把文件存成了GBK编码，却在文件头写着coding: utf-8，那代码跑起来照样会报编码错误，甚至中文注释都会乱码。

实操建议是：用现代编辑器（VS Code、PyCharm等）时，把默认编码设为UTF-8，然后完全不用手写编码声明。如果哪天接手了老项目，看到编码声明，先确认文件实际编码和声明一致，再动手改代码。

3. 标识符：每一个名字都必须合法合规

3.1 Python标识符的硬性规则

标识符（Identifier）就是你在代码里给变量、函数、类、模块起的名字。Python对标识符有一套硬性语法规则，违反任何一条都会直接报错。别小看这些规则，我在论坛上看到太多新人因为中文标点、数字开头、空格混入而反复碰壁。

合法标识符必须同时满足以下条件：

第一，只能由字母、数字、下划线组成，不能有空格、标点、运算符。这个"字母"在Python 3里可以包含非ASCII字符（比如中文），但后面会专门说为什么我不建议你写中文标识符。像my var、my-var、my$var这些全都不合法。

第二，不能以数字开头。1var是错的，var1是对的。原因很朴素：Python解释器遇到以数字开头的东西，会优先尝试把它解析成一个数字字面量，比如1var会被拆成1和var，这就会造成歧义，所以语法上直接禁止。

第三，不能是Python的关键字（保留字）。比如if、for、while、class、def、import这些，它们已经被语言本身征用了，不能再当作变量名。后面第四部分会专门讲。

第四，标识符对大小写敏感。name、Name、NAME是三个完全不同的标识符。这点对很多以前写HTML、或者习惯随意大小写的人来说是个坎，你会看到有人定义了变量user_name，后面输入User_Name去访问，结果报NameError，就是因为大小写对不上。

第五，Python 3允许用中文等Unicode字符做标识符。比如年龄 = 18在语法上是合法的，能吃但未必好吃。原因后面展开。

3.2 命名规范是写给协作伙伴的

硬性规则解决"能不能用"的问题，命名规范解决"好不好用"的问题。Python官方有一份著名的风格指南PEP 8，其中规定了不同类别对象的命名方式，这是社区多年沉淀的共识。我在下面整理成一张表：

从实操角度，我给出的建议是：变量名要短，但不能短到失去信息。n不如count，lst不如items。同时要避免和内置函数、常用库的命名冲突。比如你定义一个变量叫list，之后想用list()构造列表就全乱了——这虽然合法，但属于自找麻烦。

还有一个贴近现实的经验：团队协作中，命名风格比个人偏好更重要。如果一个团队约定用snake_case，你就别想着用camelCase显得特立独行。代码审查时最常见的争论往往就是命名问题。与其纠结哪种风格"更美"，不如直接服从PEP 8，因为GitHub上99%的Python项目都长这样，你的代码风格越接近主流，别人阅读成本越低。

3.3 常见命名场景的推荐做法

光记住规则不够，你还需要知道真实项目里具体怎么取名。我总结了几个高频场景，都是我实际写代码时验证过好用的套路。

场景一：布尔变量。建议用is_,has_,can_开头，让变量名读起来像一个问题。比如is_valid、has_permission、can_retry。这样在if判断里代码非常自然：

if is_valid and has_permission: do_something()

场景二：函数名用动词或动词+名词。函数是行为，行为需要动词。get_user_by_id()永远比user_data()更像一个函数。如果函数会返回布尔值，同样沿用is_、has_前缀。例如is_prime(n)、has_duplicate(items)。

场景三：临时变量。循环里的元素可以直接用item、value、k、v这类短名，但前提是循环体很短，范围一眼可见。一旦循环体超过5行，短名的优势就消失了，还是用有意义的全名比较稳妥。

场景四：下划线开头的作用。单下划线开头，比如_private_data，并不是Python语法强制禁止外部访问（和Java的private不同），它只是一个"约定信号"：这个属性是内部实现细节，外部代码别碰。双下划线开头的东西，比如__secret，会在类继承中触发"名称修饰"机制，把名字改写成_ClassName__secret，这个机制比较绕，初学阶段只需要知道"有双下划线开头的名字最好别碰"即可。

3.4 两个容易忽略的细节：大小写与下划线

这里展开两个我在实际调试中遇到最多的坑。

坑一：大小写不一致。前面说了Python对大小写敏感。很多新手习惯写代码时随手用userName，但定义变量时用的是user_name，运行时会报NameError。这类错误的特点是非常隐蔽——你在编辑器里看着两个名字"好像差不多"，但解释器非常较真，一点不差才算同一个标识符。排查方式很简单：打开编辑器的"区分大小写"搜索功能，定位所有出现的地方，统一命名。

坑二：下划线被中文输入法吃掉。这是我在答疑时见过频率最高的低级错误。有些输入法在中文模式下按Shift组合键，会把英文的_替换成中文的全角破折号或顿号，肉眼几乎看不出来，但Python解释器会立刻报错SyntaxError: invalid syntax。排查的时候，把光标移到下划线附近，按方向键移动，如果感觉字符宽度不对劲，多半就是中英文符号混用了。这类错误防不胜防，唯一的好办法是：刚学的时候尽量切换到纯英文输入法写代码，包括标点符号、下划线、括号，全部统一用半角。

4. 关键字与内置函数：不能踩的雷区

4.1 关键字为什么不能当标识符

关键字（keyword）是Python语言预留的特殊词，它们每个都有被解释器特殊对待的语法含义。大家熟悉的if、elif、else、for、while、def、class、return、import、from、try、except、finally、with、and、or、not等等，都属于这一类。

从原理上讲，解释器解析代码时，会先把源码切分成一个个token（词法单元）。如果允许你用if = 3，那么解释器读到if这个token时，就不知道该把它当作关键字来处理if分支逻辑，还是当作变量名来赋值——这会造成语法上的二义性。所以语言设计者干脆规定：这些词是保留的，谁都不能拿来当标识符。

Python 3里关键字一共有30多个，具体版本之间略有差异。你不需要死记硬背，完全可以当场验证：

import keyword print(keyword.kwlist) print(len(keyword.kwlist))

运行后你会看到一份按字母排序的关键字列表。以后只要不确定某个词能不能当变量名，跑一下这个检查就行。还有更简单的办法：你直接在交互式环境里执行if = 1，解释器会立刻用SyntaxError: invalid syntax教你做人。

4.2 一个小实验：把关键字当作变量名会发生什么

为了加深印象，我们做个非常短的小实验。打开Python交互式环境（终端里输入python回车），依次输入下面的代码：

>>> class = "hello" File "<stdin>", line 1 class = "hello" ^ SyntaxError: invalid syntax

注意报错信息，Python会把光标位置精准地指到class后面的空格处，因为它在词法分析的阶段就发现了这里不该出现关键字。这种现象也侧面说明，Python解释器的错误信息其实很友好，往往直接指出问题位置，你要学会看报错信息而不是凭感觉猜。

再看看另一个高频错误——用了内置函数名做变量名：

>>> list = [1, 2, 3] >>> list((1, 2, 3)) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'list' object is not callable

看到没？这段代码在语法上完全合法，不会报SyntaxError，但运行时它把list这个名字覆盖成了列表对象，导致原本的list()函数失效。这种错误比关键字更坑，因为它不报编译错，只在运行时引爆，排查起来更费劲。

我的建议是：把list、dict、str、int、type、id、input、print这些高频内置函数名都当作"准保留字"，一律不要用作变量名。如果你确实需要一个"列表"变量，就叫items、values、numbers，而不是list。

4.3 别用内置函数名做变量名

内置函数名被覆盖，属于初学阶段最容易踩的雷。除了list，还有几个典型：

这些覆盖行为在短脚本里可能"碰巧"没事，但一旦代码变长，早先的赋值语句覆盖了内置名，后面的代码就会莫名其妙地TypeError。检查的办法也很简单：在编辑器里按住Ctrl点击变量名（PyCharm或VS Code都支持），如果跳转到了Python内置模块的定义，说明名字被正常解析为内置函数；如果跳到了你自己的某一处赋值语句，那就要小心了——你已经覆盖了它。

这个雷之所以值得专门强调，是因为它完全不符合新手对"报错应该发生在出错那一行"的直觉。你可能在文件第200行定义了list变量，然后第20行的list(...)就遭殃了，错误报在第20行，排查时你大概率先怀疑第20行写错了，半天想不起来第200行的存在。所以养成好习惯，从第一天起就避开内置函数名，比事后Debug省一百倍力气。

5. 实战练习：检验这15分钟的学习效果

既然标题叫"练习-01"，光看不练等于没学。我这几年带人的经验是：基础阶段最忌讳"眼睛会了，手不会"。下面三道题，难度是递进的，从"找错误"到"判断合法性"再到"动手改造"，建议你认真把它们做完再翻参考答案，否则练习效果会打对折。

5.1 练习一：给一段代码挑刺

下面的代码存在多处和"注释""标识符"相关的问题，请逐行找出并说明理由：

# 计算平均分 1st_score = 89 2nd_score = 95 3rd_score = 87 total_score = 1st_score + 2nd_score + 3rd_score average = total_score / 3 print("平均分是：" + average) # 输出结果

先别急着跑，直接读代码找问题。提示：总共至少5处。

5.2 练习二：给变量名"合法体检"

请判断下面的标识符哪些合法、哪些不合法，并说明原因：

age _age age_1 1_age True true class_name class 用户名 user-name user name _is_valid_ for

5.3 练习三：改造一段"坏味道"代码

下面这段代码能运行，但读起来非常痛苦。请按照第二部分和第三部分讲的规范和风格，重构它：

def f(a, b): # 计算两组数据的重叠部分长度 s1 = set(a) s2 = set(b) c = len(s1 & s2) return c list1 = [1, 2, 3, 4, 5] list2 = [4, 5, 6, 7, 8] result = f(list1, list2) print(result)

要求：函数名改用动词短语；变量名清晰表达含义；注释重写，说明"为什么"而不是"是什么"；避免覆盖内置函数名。

5.4 练习参考答案

练习一：

• 1st_score、2nd_score、3rd_score：以数字开头，非法标识符，解释器直接报SyntaxError；
• print("平均分是：" + average)：average是浮点数，不能直接和字符串用+拼接，运行时需要改成f"平均分是：{average}"；
• 最后的行尾注释# 输出结果是典型的"废话注释"，没有解释任何"为什么"，建议删除或补充说明；
• 头部注释# 计算平均分如果只是为了说明代码作用，可以保留，但更好的做法是让代码本身通过变量名表达这个意图。

练习二：

• age：合法；
• _age：合法，单下划线开头表示私有约定；
• age_1：合法，数字不在开头；
• 1_age：不合法，数字开头；
• True：不合法，True是Python关键字，表示布尔真值；
• true：合法，因为大小写不同，它不是关键字（但尽量别用，容易和True混淆）；
• class_name：合法，很常见；
• class：不合法，关键字；
• 用户名：合法，Python 3支持Unicode标识符，但不推荐在协作项目中使用；
• user-name：不合法，连字符-会被当成减号，标识符不允许；
• user name：不合法，空格不允许出现；
• _is_valid_：合法，但双下划线前后都有特殊约定（魔术方法），普通场景不建议这样命名；
• for：不合法，关键字。

练习三，参考改法：

def count_overlap(first_items, second_items): """计算两组数据集合的交集元素个数。 参数: first_items: 可迭代对象，例如列表 second_items: 可迭代对象，例如列表 返回: 交集元素的个数 """ first_set = set(first_items) second_set = set(second_items) overlap_count = len(first_set & second_set) return overlap_count scores_a = [1, 2, 3, 4, 5] scores_b = [4, 5, 6, 7, 8] overlap_count = count_overlap(scores_a, scores_b) print(overlap_count)

几个改动点说明：函数名f改成了count_overlap（动词短语，表意清晰）；参数a, b改成了first_items, second_items；内部临时变量c改成了overlap_count；list1、list2改成了scores_a、scores_b，避免覆盖list内置函数；同时把注释升级成了docstring，这样help()能看到文档。

6. 新手最容易踩的四个坑

6.1 中文输入法混入全角符号

这个坑我在前面已经提过一次，但值得再强调，因为它几乎每个新手都会遇到，而且极其隐蔽。典型场景：你想给变量起名user_name，输入下划线时，如果中文输入法处于中文标点状态，实际上输入的是中文的"下划线"（占两个字符宽度）。代码看着没区别，但解释器一遇到就SyntaxError。

我的排查技巧是：在报错的代码行里按方向键移动光标，如果光标移动的格数比字符数多，说明有隐藏字符。更省事的是显示空白字符：VS Code里勾选"Render Whitespace"，PyCharm里设置"Show whitespace"，非ASCII字符会显示成不同的颜色或宽度。总之一句话，写代码时永远保持英文输入法在全半角正确状态，特别是括号、引号、下划线这几个高危字符。

6.2 复制粘贴导致的下划线丢失

还有一类问题源于复制粘贴。从网页、PDF、聊天窗口复制代码时，较长的下划线___有时候会被复制成三个短横---，或者双下划线__被折叠成单下划线_。这在你定义__init__、__name__这类魔术方法时尤其致命——因为双下划线前后都有意义，少一个下划线，Python解释器就把你的方法当普通方法处理，类实例化时根本不会调用到它。

实操建议：核心代码尽量手动敲，不要整段从网页复制；如果非要复制，粘贴后先跑一次语法检查（编辑器里的错误提示、或者python -m py_compile 文件名.py），确认无误再进行下一步。

6.3 注释不更新的"僵尸注释"

这部分内容属于代码维护阶段的真实经验。写注释不难，难的是让注释永远和代码保持同步。很多老项目里，代码改了好几轮，注释还停留在最初版本——这就成了"僵尸注释"，比没有注释更误事。因为后来接手的人如果相信注释，会按照错误的说明去理解代码，轻则浪费半天时间，重则把正确逻辑改坏。

我个人的原则是：改代码时，必须同步看一眼相关注释。如果注释和代码对不上了，要么改注释，要么删注释，不要留着一句过时的解释。这个习惯看起来琐碎，但在长期维护的项目里，它直接决定你的代码十年后还能不能被别人（包括未来的你自己）看懂。

6.4 纠结命名时的完美主义

新手容易走另一个极端：起个变量名想了十分钟，觉得这个不够准确，那个不够优雅。我在实际项目里的经验是：命名要用心，但不要过度纠结。变量名只要满足"见名知义、能读出来、不产生误解"这三个标准，就已经合格了。与其花十分钟想一个完美的名字，不如快速用一个合格的名字，然后继续往下写，等代码写完了，回头看整体结构时再统一优化命名。

这里有个非常实用的技巧：先用一个足够描述性但不完美的名字（比如temp_data），把逻辑跑通，然后在重构阶段用编辑器的"重命名"功能批量修改。PyCharm和VS Code都支持对整个项目内的标识符做安全重命名，比你一开始抠字眼高效得多。编程是迭代的艺术，第一次写得不够漂亮完全可以接受，关键在于你有意识地在后续循环里改进它。

就我个人而言，每次带新人入门，我都会把这些"坑"提前摆出来，让他们在第一天就建立"代码是给人看的，顺带让机器执行"的认知。注释和标识符看似基础，却是这份认知最直接的载体。下一篇系列练习，我会接着讲变量和基础数据类型，到时候你会发现，这一篇打下的底子，会让后面的一切顺利很多。