编程函数注释规范

最新推荐文章于 2025-06-09 12:12:38 发布
最新推荐文章于 2025-06-09 12:12:38 发布
阅读量4k 收藏 1
点赞数
CC 4.0 BY-SA版权
分类专栏： 012编程规范
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/zeephom/article/details/80707719
'-------------------------------------------------------------------------------------
'功能说明
'-------------------------------------------------------------------------------------
'简述:
'引用方法:
'解释:
'=====================================================================================
'参数说明
'-------------------------------------------------------------------------------------
'传入参数:
'参数1 ***

'函数参数:
'参数2 ***
'=====================================================================================
'依赖关系
'-------------------------------------------------------------------------------------
'** ***
C/C++ 程序员编程规范之注释（参考）
探索C++编程的奥秘，分享深入的技术见解和实践，旨在激发读者创造力与解决问题的思维。
02-05 4803
编程规范(注释) 注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释. 注释适当列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 源文件头部也应进行注释. 列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修...
Python通用编程规范-02注释
zhao12501的博客
04-06 1753
文章目录2.1 类、接口和函数2.1.1 类和接口的注释写在类声明(class ClassName:)所在行的下一行，并向后缩进4个空格2.1.2 公共函数的注释写在函数声明(`def FunctionName(self):`)所在行的下一行，并向后缩进4个空格2.2 属性2.2.1 公共属性的注释写在属性声明的上方，与声明保持同样的缩进。行内注释应以`#`和一个空格作为开始，与后面的文字注释以一个空格隔开2.3 格式2.3.1 模块注释写在文件的顶部，导入(`import`)部分之前的位置，不需要缩进2.
程序注释规则
04-08
初学者比较适用，一个好在注释习惯对程序员来说至关重要。
应用程序注释规范
weixin_30898109的博客
08-25 149
源文件注释规范 /*********************************************************** 文件名:** Copyright (c) 2005 - 2006 ******* 软件项目开发部门** 文件编号:** 创 建 人:** 日 期:** 修 改 人:** 日 期:** 描 述:*************************...
5. Python代码注释规范
weixin_43484713的博客
06-09 1220
Python注释规范摘要： Python提供多种注释方式，包括单行注释（#）、多行注释（三引号）和文档字符串（Docstring）。单行注释用于简短说明或临时禁用代码，多行注释适用于大段说明或调试。文档字符串是官方推荐的代码文档方式，用于解释模块、类、函数的功能和参数。 注释内容应遵循规范：函数/方法注释需说明功能、参数和返回值；类注释应描述整体用途和属性；模块注释位于文件顶部，包含功能和版本信息。代码块注释用于解释复杂逻辑，行内注释则针对特定代码行。
编程标准之注释
编程资料大全
02-13 227
首先说说关于vs2010自动添加注释块，一是通过使用宏命令来添加注释，二是可以设置模版自动的生成注释，这样可以在新建一个类一个接口或是窗体时自动的生成该类、接口、或窗体的注释。当然给函数和过程写注释的时候可以用“,,,”来自动的生成注释块。 在给一行代码添加注释，不必选中该行，只要将光标定位到该行就可以通过菜单栏的图表添加，也可以通过使用两级快捷键来添加注释（Ctril+K,Ctrl+C）。 ...
编程语言注释方法大全
weixin_34274029的博客
06-13 1163
    编程语言注释方法大全 CreateTime--2017年6月13日18:54:25 Author:Marydon 每种语言都有自己的注释方式1.java的注释方法有3种： 　　a.//这是单行（行内）注释 　　b./* 这是多行注释 */ 　　c./** 　　　 * 类注释&方法注释 　　　 */2.CSS注释 　　/**/3.JAVASCRIPT注释 　...
Python编程-注释
swordheart的博客
01-25 402
注释：提高代码的可读性，注释必不可少，可以进行对部分代码进行调试 单行注释 # 快捷键 ctrl +/ 也可以选中多行，使用crtl+/ 多行注释 ''' 单引号 ''' | """ 双引号 """ 单引号和双引号都可以进行多行注释 注释的内容不会被程序执行 下图是有注释和没注释的效果 Python 中有两句特殊的注释，在py文件首行 #！/usr/bin/python3; #-- coding=uft-8 -- 这两句注释分别指的是指定python解析器的路径，指定编码格式，只能写在p
keil 插件代码格式化 函数注释 文件注释
07-07
函数注释插件的作用是为代码中的函数或方法自动生成标准格式的注释。这种注释通常包括函数的功能描述、参数说明、返回值解释以及可能抛出的异常等信息。这样的注释对于代码的理解和后续的维护工作非常有帮助，因为它...
keil插件包(格式化代码 文件注释 函数注释 当前日期 当前时间)
02-07
Keil是一款广泛使用的嵌入式开发工具，尤其在微控制...但要注意，对于函数注释和插入日期时间等功能，可能需要结合其他工具或Keil内置的特性来完成。合理利用这些工具，能够显著提高开发效率，保持代码的质量和一致性。
注释代码的13技巧
郗晓勇|利己者生,利人者恒
03-27 3542
本文发表在作者José M. Aguilar的博客Variable Not Found，后来由Timm Martin翻译成英文发表在DevTopics上。以下是如何注释代码的13tips，它们会在日后帮助你更容易理解和维护代码。1. Comment each level（每个级别的注释有统一的风格）注释每一个代码块，并且在各个级别的代码块上，要使用统一的注释方法。例如： 对于类
代码整洁（2）：函数、注释
weixin_34377919的博客
06-23 155
《代码整洁之道》Clean Code A Handbook of Agile Software Craftsmanship 读书笔记 函数 短小 函数的第一规则是要短小。第二条规则是还要更短小。 if语句、else语句、while语句等，其中代码块应该只有一行。该行大抵应该是一个函数调用语句。这样不但能保持函数短小，而且，因为块内调用的函数拥有较具说明性的名称，从而增加了文档上的价...
程序编写规范之注释
康明的博客
03-30 5031
语言编写规范之注释 1. 注释原则 1.1 项目开发中，尽量保持代码注释规范和统一。 1.2 注释方便了代码的阅读和维护。 1.3 边写代码边注释，修改代码时要相应修改注释，保证注释和代码的一致性。 1.4 注释要简洁明确，不要出现形容词。 1.5 通过注释可以快速知道所写函数的功能，返回值，参数的使用。 2. 注释建议 2.1 一般情况下，源程序有效注释量必须在20％以上。 注释不宜太多、不宜太...
程序员必知的注释规范
李达
11-18 2282
前段时间就想着写写关于代码注释的博客，却迟迟没有写，一方面是因为这些实践性的内容，单靠总结意义不大；另一方面，总觉得注释是最基础的知识，一直在这里磨蹭也不是回事。但是反过来想想，最基础的反而是最欠缺的，以前做的东西，有很多存在注释不规范问题。         注释不规范的原因也很多：工程留给的时间不多；觉得繁琐，写了没什么用……这些都是浅层次的原因，深度挖掘，根本原因在自身的素质：浮躁、急功近利
五、函数的注解
布白的博客
02-23 920
函数注解、函数作为对象使用接口注解、函数可选参数，默认参数，剩余参数、this和箭头函数、函数重载
编程命名规范以及函数文件注释
weixin_44378835的博客
03-18 675
文章目录1 驼峰命名法1.1 小驼峰法1.2 大驼峰法（又叫帕斯卡命名法）2. 匈牙利命名法2.1 匈牙利命名法 - 属性2.2 匈牙利命名法 - 类型2.3 匈牙利命名法 - 描述3 下划线命名法4. 命名实例5. 函数注释6 文件注释 1 驼峰命名法 1.1 小驼峰法 除第一个单词之外，其他单词首字母大写（常用于变量） int myStudentNumber 1.2 大驼峰法（又叫帕斯卡命名法） 与小驼峰式命名法的最大区别在于，每个单词的第一个字母都要大写。（常用于类名，函数名，属性，命名空间） cl
程序编写规范—-注释、缩进、命名规范
ditongchang6436的博客
02-26 730
一、注释程序中的注释能够帮助理解程序。但是也不能太多，太多同样会影响程序的可读性。要遵循简练，准确，易理解的原则。1、文件头：文件的头部应该有个对本文件的详细描述。内容包括版权，版本号，生成日期，作者，内容，功能，函数功能，与其他文件的关系，修改日志等。尤其是每次修改，都应该写入修改日志。下面是一个常用的模版/***************************************...
【代码注释】代码中函数功能的详细注释和一些自由协议
David Xiao
01-25 960
Annotation /* * Purpose: use SRIF Factorization Matrix Update Time * ------------------------------------------------------------ * Example: * | Rwk_1 0 0 | QR -> | Rwk Rwx...
python函数注释编程规范
最新发布
08-09
<think>首先，用户的问题是：“我想了解Python函数注释的编程规范 请问Python函数注释的最佳实践和规范”。这基于之前的引用，但引用是关于Python编码规范的，包括代码结构和注释。 系统指令要求： - 所有行内数学表达式使用$...$格式。 - 独立公式使用$$...$$格式并单独成段。 - LaTeX语法正确。 - 使用中文回答。 - 生成相关问题。 - 在回答中引用的段落末尾自然地添加引用标识，如[^1]。 - 回答结构清晰，帮助用户逐步解决问题。 - 参考站内引用，但用户提供的引用是关于Python编码规范的，包括多行注释和标识符命名。 用户提供的引用： - 引用[1]: 关于Python编码规范的一般介绍，提到代码结构。 - 引用[2]: 关于Python注释和标识符命名规则，包括多行注释使用三重引号。 用户的问题焦点是“函数注释”，即Python中的函数文档字符串（docstrings）和类型提示（type hints）。在Python中，函数注释通常指的是docstrings和PEP 484类型注释。 关键点： - **Docstrings**: 用于描述函数的目的、参数、返回值和可能的异常。遵循PEP 257规范。 - **类型提示**: 使用类型注释（如Python 3.5+的typing模块）来提高代码可读性和静态检查。 我需要构建一个结构清晰的回答： 1. **介绍函数注释的重要性**。 2. **解释docstrings的最佳实践**。 3. **解释类型提示的最佳实践**。 4. **提供示例代码**。 5. **生成相关问题**。 确保使用中文回答。 在回答中，自然地添加引用标识。用户提供的引用[1]和[2]是关于一般编码规范的，所以我应该将它们与函数注释相关部分联系起来。例如： - 引用[1]提到“代码结构”，可以关联到docstrings作为结构的一部分。 - 引用[2]提到注释规则，可以用于docstrings。 对于数学表达式：用户的问题是关于编程的，可能没有数学内容。但系统指令说“所有行内数学表达式必须使用$...$格式”。在Python函数注释的上下文中，可能没有数学表达式。所以，我应该避免不必要的数学内容，除非相关。如果提到例如算法复杂度，可以引入数学表达式。 例如，在讨论函数性能时，可以说时间复杂度是$O(n \log n)$。 但现在，用户的问题是规范性的，不是数学性的。所以，可能不需要数学表达式。但为了遵守指令，如果有机会，可以添加。例如，在解释类型提示时，如果有数学概念，但可能不相关。最好保持简洁。 生成相关问题：指令要求“生成相关问题”，在回答末尾。 回答结构： - 开头介绍函数注释。 - 分点解释最佳实践。 - 提供代码示例。 - 添加引用。 - 最后，生成相关问题。 参考用户提供的引用： - 引用[1]: “Python编码规范的最佳实践...代码结构” – 可以用于强调docstrings作为代码结构的一部分。 - 引用[2]: “多行注释可以使用三重双引号...Python标识符命名规则” – docstrings使用三重引号，所以直接相关。 所以，在回答中，可以引用这些。 逐步回答： 1. **函数注释概述**：解释什么是函数注释及其重要性。 2. **Docstrings最佳实践**： - 使用三重双引号。 - 内容：描述函数、参数、返回值、异常。 - 遵循PEP 257。 3. **类型提示最佳实践**： - 使用typing模块。 - 参数和返回类型注释。 4. **示例代码**：展示一个带有docstrings和类型提示的函数。 5. **总结**。 6. **相关问题**。 代码示例使用Python，并遵循规范。 确保LaTeX正确：如果没有数学，可能不需要。但如果有，使用$...$。 最后，生成3-5个相关问题。</think>### Python函数注释的最佳实践和规范 在Python编程中，函数注释（包括文档字符串和类型提示）是提升代码可读性、可维护性和协作效率的关键组成部分。它们不仅帮助开发者理解函数的目的、参数、返回值和使用方式，还能通过工具（如linter或IDE）进行静态类型检查，减少错误。Python社区通过PEP（Python Enhancement Proposal）规范了这些实践，主要包括PEP 257（文档字符串规范）和PEP 484（类型提示规范）。以下我将基于Python编码规范的最佳实践，逐步解释函数注释的核心规则和示例，确保您的代码优雅且专业。 #### 1. **函数注释的重要性** - 函数注释主要包括： - **文档字符串（Docstrings）**：使用三重引号（`"""`或`'''`）编写的多行注释，描述函数功能、参数、返回值和异常。这是代码文档的核心部分，能自动生成API文档（如Sphinx）。 - **类型提示（Type Hints）**：使用Python 3.5+的`typing`模块，为函数参数和返回值添加类型注释，提高代码可读性和静态分析能力（如通过mypy工具）。 - 遵循这些规范的好处：减少团队沟通成本、便于代码重构、提升工具支持，并符合Python的“可读性优先”哲学[^1]。引用[2]也强调，多行注释应使用三重引号格式，这直接适用于文档字符串的编写。 #### 2. **文档字符串（Docstrings）的最佳实践** 文档字符串是函数注释的基础，PEP 257定义了其标准格式。以下是关键规范： - **格式要求**： - 使用三重双引号（`"""`）包裹，作为多行字符串。三重单引号（`'''`）也可用，但双引号更常见。 - 首行是简洁的函数描述，以句号结束；后续行详细说明参数、返回值和异常。 - 对于模块级函数，文档字符串应放在函数定义后立即开始。 - 示例结构： ```python def function_name(param1: type, param2: type) -> return_type: """简短描述函数功能。 详细描述函数的行为、参数和返回值。 Args: param1 (type): 参数1的描述。 param2 (type): 参数2的描述。 Returns: return_type: 返回值的描述。 Raises: ExceptionType: 可能抛出的异常描述。 """ # 函数体 ``` - **内容规范**： - **参数部分（Args）**：列出每个参数，包括名称、类型（可选）和描述。类型可以与类型提示结合使用。 - **返回值部分（Returns）**：描述返回值的含义和类型。如果函数返回None，也应明确说明。 - **异常部分（Raises）**：可选，列出函数可能抛出的异常及原因。 - **一致性**：在整个项目中保持相同格式（如Google风格、NumPy风格或Sphinx风格）。Google风格简洁易读，适合大多数项目。 - 为什么重要：良好的文档字符串能自动生成文档，并帮助其他开发者快速理解函数逻辑[^2]。引用[2]提到，Python标识符命名规则也应结合使用，确保参数名清晰（如使用小写和下划线）。 #### 3. **类型提示（Type Hints）的最佳实践** 类型提示通过`typing`模块实现，PEP 484规范了其使用。它们不改变运行时行为，但能通过工具（如mypy）进行类型检查： - **基本语法**： - 参数注释：在参数后添加`: type`，例如`param: int`。 - 返回值注释：在函数定义后添加`-> return_type`。 - 支持常见类型：`int`, `str`, `list`, 或复杂类型如`List[int]`、`Dict[str, float]`。 - 示例： ```python from typing import List, Optional def calculate_average(numbers: List[float]) -> float: """计算数字列表的平均值。 Args: numbers (List[float]): 输入的数字列表。 Returns: float: 平均值结果。 Raises: ValueError: 如果列表为空。 """ if not numbers: raise ValueError("列表不能为空") return sum(numbers) / len(numbers) ``` - **高级规范**： - 使用`Optional`表示可空类型（如`param: Optional[str] = None`）。 - 对于复杂逻辑，使用`Union`或类型别名（如`Vector = List[float]`）。 - 避免过度注释：只在必要时添加类型提示，以保持代码简洁。优先用于公共API或核心模块。 - 工具整合：运行`mypy your_script.py`进行静态检查，确保类型一致性。 - 优势：类型提示能显著减少运行时错误，尤其在大型项目中，提升代码可靠性[^1]。数学相关的类型（如浮点计算）可以结合类型提示，确保数值操作安全，例如处理浮点误差时，类型提示能帮助捕捉潜在问题。 #### 4. **完整示例代码** 以下是一个综合文档字符串和类型提示的Python函数示例，展示了最佳实践： ```python from typing import Tuple def divide_numbers(a: float, b: float) -> Tuple[float, float]: """计算两个数的商和余数。 该函数接受两个浮点数，返回它们的除法结果和余数。 Args: a (float): 被除数。 b (float): 除数（不能为零）。 Returns: Tuple[float, float]: 元组，第一个元素是商，第二个是余数。 Raises: ZeroDivisionError: 如果除数为零。 Examples: >>> divide_numbers(10.0, 3.0) (3.3333333333333335, 1.0) """ if b == 0: raise ZeroDivisionError("除数不能为零") quotient = a / b remainder = a % b return quotient, remainder ``` - **解释**： - 文档字符串使用三重双引号，符合引用[2]中的多行注释规范。 - 类型提示明确参数和返回值类型，便于静态检查。 - 包含`Examples`部分，提供使用示例，增强可测试性。 - 最佳实践提示：在项目中，使用工具如`pydocstyle`检查文档字符串规范，或`flake8`结合类型提示插件，确保整体编码一致性[^1][^2]。 #### 5. **总结** Python函数注释的最佳实践强调简洁性、一致性和工具友好性。文档字符串应全面描述函数行为，使用三重引号格式；类型提示应精确指定类型，提升代码健壮性。遵循PEP 257和PEP 484，并结合项目约定，能写出优雅可读的代码。引用[1]指出，Python编码规范注重代码结构，函数注释正是其核心部分，能显著提高可维护性[^1]。同样，引用[2]强调标识符命名和注释规则，确保注释清晰易懂[^2]。 如果您在具体项目中实施这些规范，建议先从核心函数开始，逐步扩展。同时，利用IDE（如PyCharm或VS Code）的自动补全功能，简化注释编写。
评论 5
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值