企业官网建设流程全解析

• 示例工程
• 教程

导读

注释是 Python 代码中最简单却最常被忽视的基础语法。本文以 c9-python-getting-started 仓库中 python-for-beginners/03 - Comments 模块为骨架，系统讲解#号注释的语法规则、执行行为，并结合仓库配套源码演示「为代码写说明」与「用注释做调试」两大核心用途。读完本文，你将能正确书写注释、利用注释定位 bug，并理解注释与字符串、docstring、README 之间的边界关系。

一、注释的语法规则：以#开头，执行时被忽略

原文档给出了两条最核心的定义：

Comments start with a hash character (#) and allow you to document your code. Comments are ignored when code is executed.

翻译成技术要点就是：

• 注释以井号字符#开头；
• 注释用于为你的代码书写说明文档；
• 解释器执行代码时，注释会被完全忽略。

#之后的同一行内容全部属于注释，注释一直延续到该物理行的行尾，换行即结束。这条规则在 Python 官方词法分析（lexical analysis）规范中有明确对应，也正是原文档链接指向的官方文档主题。

运行验证：注释确实不产生任何输出

仓库中的 comments_are_not_executed.py 用一个极简示例直观展示了「注释不被执行」：

# This is a comment in my code it does nothing # print('Hello world') # print("Hello world") # No output will be displayed!

整个文件全是注释，其中甚至包含两行被注释掉的print('Hello world')调用。实际运行该文件：

python3 "python-for-beginners/03 - Comments/comments_are_not_executed.py"

终端不会输出任何内容，程序以状态码 0 正常结束——即使你把整段「打印语句」写进注释里，它们也永远不会被执行。这验证了注释的第一大特性：注释是写给人和工具看的，不是写给解释器看的。

二、注释的两大核心用途：写说明与做调试

原文档强调注释的作用是 "document your code"，而仓库配套代码恰好示范了注释在真实开发中的两种典型用法。

2.1 用途一：为代码书写说明文档

enable_pin.py 是一个带完整注释的、可运行的 PIN 功能示例：

#The enable_pin method is not coded yet # I have created a dummy method so the code # will run without an error # Don't panic if you don't understand this part of the code # we cover methods in a separate module def enable_pin(user, pin): print('pin enabled') # Set current_user and pin to test values current_user = 'TEST123' pin = '123456' # Enable PIN check as listed in # security requirements enable_pin(current_user, pin)

这个示例展示了注释的多个重要用法：

• 解释设计意图：注释先说明enable_pin方法尚未真正实现、当前只是占位（dummy method），避免读者误以为这是最终代码；
• 安抚读者、指引学习路径：注释明确提示「方法（methods）会在后续模块中讲解」，让初学者不被未知语法吓退；
• 标注变量用途：# Set current_user and pin to test values说明下面两行是测试数据；
• 关联需求文档：# Enable PIN check as listed in security requirements把代码与安全需求条目建立对应关系，这是工程实践中「代码可追溯」的起点。

运行该文件会输出pin enabled，说明注释之外的代码正常工作，注释对运行结果零影响。

2.2 用途二：临时禁用代码，辅助调试

调试时最常见的操作就是「注释掉一行代码，看看去掉它之后程序行为是否变化」。仓库中 comments_for_debugging.py 从文件名上看就是为演示这一场景而准备的：

print('Hello world') print('It's a small world after all')

这个文件故意保留了第二个print中的语法问题（'It's ...在单引号字符串内嵌套了未转义的单引号）。运行它会得到：

SyntaxError: unterminated string literal (detected at line 2)

把调试思维套进来：如果某一行代码疑似有问题，你可以先用#把它注释掉、运行其余部分，确认问题是否由该行引起——这正是「注释用于调试」的标准流程。同时它也提醒我们：注释可以帮你绕过有问题的代码行，但不会修复真正的语法错误，错误最终还是需要修改代码本身来解决。

对比 comments_are_not_executed.py：把print('Hello world')完整注释掉后文件可以零报错运行；而 comments_for_debugging.py 的问题出在字符串内部，#注释无法触及，所以仍会报错。这恰好说明了「#注释的边界」——下面第四节会展开。

三、注释的编写实践：位置、时机与可读性

3.1 独立行注释与行尾注释

从上面的仓库示例可以看出，Python 中最常见的注释形态是独立成行（整行以#开头）。此外，注释也可以跟在代码行末尾（行尾注释 / trailing comment）：

current_user = 'TEST123' # 测试用户 pin = '123456' # 测试 PIN

无论哪种形态，解释器都会在词法分析阶段把#到行尾的内容丢弃，不影响该行代码的执行。

3.2 注释应该解释「为什么」，而不是复述「做什么」

一个常见误区是写「冗余注释」，例如：

x = x + 1 # 把 x 加 1

这样的注释只是把代码翻译成中文，没有额外信息量。更好的注释应该说明动机与约束，例如 enable_pin.py 中# Enable PIN check as listed in security requirements就交代了「为什么必须有这段调用」。

3.3 注释与字符串引号的关系

本模块的 string_in_double_quotes.py 虽然是关于字符串引号选择的示例，但它同样示范了「注释辅助解释决策」的写法：

# Using double quotes for this string because # the string itself contains a single quote print("It's a small world after all")

这里注释解释了「为什么用双引号」——因为字符串内容本身包含单引号。这正是 2.2 节中'It's a small world after all'报错的正确解法：改用双引号包裹即可避免引号冲突。可见，一句到位的好注释，往往能把一个易错点讲清楚，避免后人踩同样的坑。

四、理解注释的边界：#与字符串、shebang 的区别

4.1 字符串里的#不是注释

#只有在不属于字符串字面量的一部分时才表示注释开始。例如：

print("# this is not a comment")

这行代码中的#位于双引号字符串内部，会被当作普通字符打印出来，绝不会触发注释解析。这一点在 Python 官方词法分析规范中有明确表述（"A comment starts with a hash character (#) that is not part of a string literal"）。

4.2 文件首行的#!（shebang）

如果#出现在脚本第一行且紧跟!，它构成 shebang 行（如#!/usr/bin/env python3），用于告诉操作系统用哪个解释器执行该脚本。shebang 在语法上同样是注释（会被忽略），但语义特殊。在本仓库的 python-for-beginners 课程示例中，所有.py文件均未使用 shebang，直接通过python3 文件名.py运行，可见对初学者而言这并不是必需项。

五、从注释到三层文档化体系：注释、docstring 与 README

原文档指出注释让你能够 "document your code"，而一个工程化的 Python 项目通常有三层文档载体，注释只是其中一层：

以仓库 good.py 为例，它示范了标准 docstring 的写法——用三引号包裹，并结构化描述参数（Parameters）与返回值（Returns）：

def print_hello(name: str) -> str: """ Greets the user by name Parameters: name (str): The name of the user Returns: str: The greeting """ print('Hello, ' + name)

docstring 与#注释的区别在于：docstring 是真实存在的字符串表达式，能被help()、IDE 提示和文档生成工具读取；而#注释在词法阶段就被丢弃，纯粹服务于人类阅读。两者分工互补：短小、临时的说明用#，正式、可被工具消费的接口说明用 docstring。

再往上一层，03 - Comments/README.md 本身就是一个 Markdown 注释——用人类可读的文档格式介绍模块主题、并链接到 Python 官方词法分析文档（该链接是原文档中唯一的官方参考资料，建议进阶阅读）。

六、常见误区自查清单

结合本模块源码与运行结果，初学者应特别注意以下几点：

1. 注释不会执行：被#注释掉的代码不会运行，comments_are_not_executed.py 已验证；
2. 注释不是语法错误的解药：字符串内部的语法错误（如 comments_for_debugging.py 的SyntaxError: unterminated string literal）无法通过外部加注释解决，必须修正字符串本身的写法；
3. #在字符串内是普通字符：不要误以为字符串里的#会开启注释；
4. 注释应解释动机：多写「为什么」，少写「是什么」，参见 string_in_double_quotes.py 的注释写法；
5. 善用注释做调试：怀疑某行代码有问题时，先注释掉它再运行，快速缩小排查范围（enable_pin.py 中的注释块也展示了如何临时「关掉」尚未实现的代码让程序先跑通）。

七、小结

注释是 Python 语法中最轻量的部分，却承担着代码可读性、可维护性与可调试性的重任。核心规则只有两条：以#开头、执行时被忽略，但把它用好的关键在于：为代码补充说明、为调试提供开关、为后人解释动机。本模块的四个配套示例（comments_are_not_executed.py、comments_for_debugging.py、enable_pin.py、string_in_double_quotes.py）都值得逐一运行验证。掌握注释之后，你就可以放心进入下一个主题——字符串变量，那里你将看到注释与字符串引号规则的更多配合场景。

• 示例工程
• 教程