4.【Python】Python3 注释

第一步分析与整理 注释1. 注释的作用不影响程序执行只提高可读性。帮助理解代码逻辑方便团队协作。2. 单行注释以#开头直到行末的所有内容均为注释。# 这是一个注释print(Hello, World!)# 这也是注释3. 多行注释使用三个单引号或三个双引号包围的字符串字面量如果不赋值给变量且不被使用可当作多行注释。方式一三个单引号#!/usr/bin/python3 这是多行注释用三个单引号 这是多行注释用三个单引号 print(Hello, World!)方式二三个双引号#!/usr/bin/python3 这是多行注释用三个双引号 这是多行注释用三个双引号 print(Hello, World!)⚠️注意多行注释不能嵌套。内部再出现或会导致语法错误。错误示例 外层注释 内层注释实际上会提前结束外层注释导致语法错误 正确做法在多行注释内部使用单行注释。 外层多行注释 # 内部单行注释安全 # 另一个单行注释 4. Docstring文档字符串Docstring 是 Python 特有的正式文档注释用于函数、类、模块。它不是普通注释而是可以通过__doc__属性或help()函数访问的字符串。基本语法用三个双引号或三个单引号放在函数/类/模块的第一条语句位置。defadd(a,b):返回两数之和returnabprint(add.__doc__)# 输出: 返回两数之和help(add)# 显示帮助信息使用inspect模块提取importinspectprint(inspect.getdoc(add))# 输出: 返回两数之和多行 Docstring 示例包含参数和返回值说明defcalculate(a,b,operationadd): 执行数学运算 参数: a: 第一个数字 b: 第二个数字 operation: 操作类型可选 add, subtract, multiply 返回: 计算结果 ifoperationadd:returnabelifoperationsubtract:returna-belifoperationmultiply:returna*belse:raiseValueError(不支持的操作)类的 DocstringclassPerson:人物类用于表示一个人的基本信息def__init__(self,name,age): 初始化人物对象 参数: name: 姓名 age: 年龄 self.namename self.ageagedefintroduce(self):介绍这个人returnf我叫{self.name}今年{self.age}岁Docstring 常见风格Google 风格使用缩进和标签如参数:、返回:。Sphinx/reST 风格使用:param name:、:return:。NumPy 风格类似 Google但格式略有差异。建议在项目中保持一致风格。第二步费曼学习法教学核心思想注释是写给“未来的你”和同事看的写代码时电脑只关心指令不关心你的思考过程。但是当你一个月后回来改代码或者同事接手你的项目时注释就是救命稻草。1. 单行注释随手记笔记#后面的内容会被解释器忽略。什么时候用解释某一行难懂的代码、标记 TODO、临时禁用一行代码。xx1# 计数器加1这注释有点多余# 复杂的正则表达式最好写注释说明意图2. 多行注释用字符串“假扮”注释Python 没有真正的多行注释语法但你可以用三个引号括起来的字符串只要不把它赋给变量它就不会产生任何效果。这就像在代码里贴了一张便利贴。注意陷阱不能嵌套内部不能再有三个引号。3. Docstring正式文档可被程序读取这是 Python 的特色。写在函数、类、模块开头的三引号字符串不仅是注释还可以通过help()或.__doc__被工具提取。好处自动生成文档如 Sphinx。IDE 会弹出提示显示函数参数和返回值说明。强制自己写清晰的 API 说明。什么时候用任何公开的函数、类、模块都应该写 Docstring。私有内部函数可以省略或简单说明。4. 如何学习与应用习惯养成写任何函数前先写一行 Docstring 描述功能哪怕只有一句话。阅读标准库print(print.__doc__)看看 Python 自带的文档怎么写。使用工具在 VS Code 或 PyCharm 中输入然后回车会自动生成参数模板。5. 综合示例带完整注释的计算器函数defsafe_divide(a,b): 安全地执行除法处理除零错误。 参数: a (float): 被除数 b (float): 除数 返回: float 或 None: 计算结果若除数为0则返回 None # 检查除数是否为0ifb0:print(错误除数不能为零)returnNonereturna/b# 测试代码resultsafe_divide(10,2)print(result)# 5.0通过注释读者立刻明白函数用途、参数含义、返回值情况无需阅读实现细节。第三步芯片验证工程师视角的应用示例在芯片验证中我们经常编写复杂的 Python 脚本用于生成测试向量、解析日志、控制仿真流程。这些脚本往往有几十个函数清晰的注释和 Docstring 是团队协作和长期维护的关键。下面给出一个仿真回归测试脚本的示例重点展示如何有效使用注释和 Docstring。场景描述你负责一个 RTL 模块的验证需要每天运行一批测试用例收集结果生成报告。脚本功能包括解析测试列表、运行仿真、收集输出、判断 pass/fail。#!/usr/bin/env python3# filename: regression.py# 功能: 自动化回归测试运行指定测试用例汇总结果# 作者: 验证工程师# 日期: 2026-05-15importsubprocessimportsysimporttimefrompathlibimportPath# 配置区域 # 这里集中管理所有可调参数方便修改SIMULATORvsim# 仿真器命令WORK_DIRPath(./sim_work)# 仿真工作目录LOG_DIRPath(./logs)# 日志存放目录# defrun_single_test(test_name,timeout_sec60): 运行单个测试用例捕获输出判断是否通过。 参数: test_name (str): 测试用例名称对应一个 Tcl 脚本或编译后的仿真顶层 timeout_sec (int): 超时时间秒 返回: dict: 包含以下键的字典 - name: 测试名称 - status: PASS 或 FAIL - duration: 运行时长秒 - log_file: 日志文件路径 - error_msg: 失败时的错误信息成功时为空字符串 log_pathLOG_DIR/f{test_name}.logstart_timetime.time()statusFAILerror_msg# 构建仿真命令# 假设每个测试用例有独立的 Tcl 脚本名如 test_alu.tclcmdf{SIMULATOR}-c -do{test_name}.tcl -logfile{log_path}try:# 运行子进程限制超时resultsubprocess.run(cmd,shellTrue,timeouttimeout_sec,capture_outputTrue,textTrue)# 判断通过标准仿真器返回码为0 且 日志中不含 ERRORifresult.returncode0:# 检查日志中是否有错误关键字简单示例withopen(log_path,r)asf:log_contentf.read()ifERRORnotinlog_contentandFATALnotinlog_content:statusPASSelse:error_msg日志中发现错误信息else:error_msgf仿真器返回码{result.returncode}exceptsubprocess.TimeoutExpired:error_msgf超时{timeout_sec}秒exceptExceptionase:error_msgstr(e)durationtime.time()-start_timereturn{name:test_name,status:status,duration:duration,log_file:str(log_path),error_msg:error_msg}defrun_regression(test_list_file): 从文件中读取测试用例列表依次运行生成汇总报告。 参数: test_list_file (str 或 Path): 包含测试用例名称的文件每行一个测试名 返回: dict: 统计信息包括总数、通过数、失败数、详细结果列表 # 读取测试列表忽略空行和注释行test_names[]try:withopen(test_list_file,r)asf:forlineinf:lineline.strip()iflineandnotline.startswith(#):test_names.append(line)exceptFileNotFoundError:print(f错误: 测试列表文件{test_list_file}不存在)sys.exit(1)print(f共发现{len(test_names)}个测试用例)results[]fortnameintest_names:print(f正在运行:{tname}...,end,flushTrue)resrun_single_test(tname)results.append(res)print(f{res[status]}({res[duration]:.2f}s))# 统计totallen(results)passedsum(1forrinresultsifr[status]PASS)failedtotal-passed# 生成 Markdown 报告report_pathLOG_DIR/regression_report.mdwithopen(report_path,w)asmd:md.write(# 回归测试报告\n\n)md.write(f**执行时间**:{time.ctime()}\n)md.write(f**总用例**:{total}**通过**:{passed}**失败**:{failed}\n)md.write(f**通过率**:{passed/total*100:.1f}%\n\niftotal0else无用例\n)md.write(| 测试用例 | 状态 | 耗时(s) | 日志 | 错误信息 |\n)md.write(|----------|------|---------|------|----------|\n)forrinresults:status_icon✅ifr[status]PASSelse❌log_linkf[日志]({r[log_file]})md.write(f|{r[name]}|{status_icon}{r[status]}|{r[duration]:.2f}|{log_link}|{r[error_msg]}|\n)print(f\n报告已生成:{report_path})return{total:total,passed:passed,failed:failed,results:results}# 主程序入口 if__name____main__: 脚本入口当直接运行此脚本时执行回归测试。 用法: python regression.py test_list.txt iflen(sys.argv)!2:print(用法: python regression.py 测试列表文件)sys.exit(1)# 创建必要的目录LOG_DIR.mkdir(exist_okTrue)WORK_DIR.mkdir(exist_okTrue)# 运行回归并打印简要统计statsrun_regression(sys.argv[1])print(f\n最终结果: 通过{stats[passed]}/{stats[total]})ifstats[failed]0:sys.exit(1)# 返回非零退出码便于 CI 系统识别失败sys.exit(0)详解注释的使用层次文件头注释说明脚本用途、作者、日期方便追溯。配置区域注释集中说明可调参数避免硬编码散落在代码中。函数 Docstring每个公共函数都有清晰的参数、返回值、副作用说明。其他工程师或未来的你可以不用读函数体就理解如何使用。行内注释只在复杂逻辑处添加例如# 检查日志中是否有错误关键字。简单的代码如status FAIL无需注释。为什么这样做自动化验证脚本往往要运行数月甚至数年良好的注释可以大大降低维护成本。Docstring 还可以被 Sphinx 等工具自动生成 HTML 文档方便团队分享。实际工作中的扩展可以增加--verbose参数控制打印详细程度。将结果写入数据库便于历史趋势分析。支持并行运行多个测试使用multiprocessing模块。学习建议从今天开始给你写的每个函数加上至少一行 Docstring。阅读优秀的开源项目如pytest、requests学习它们如何组织注释和文档。在代码审查时把“缺少注释”作为一项检查点。通过这个真实的验证自动化脚本你可以看到注释和 Docstring 不是锦上添花而是专业软件工程的必需品。即使你是一个人的团队养成写注释的习惯也会在未来无数次帮你节省时间。