Python代码注释规范代码实例解析
更新时间：2020年08月14日 11:35:19 作者：蓝 寅
这篇文章主要介绍了Python代码注释规范代码实例解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
一、代码注释介绍
- 注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。
- 注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。
- 在有处理逻辑的代码中，源程序有效注释量必须在20％以上。
二、代码注释分类
行注释：在符号后那一行不会被编译（显示）
块注释：被块注释符号中间的部分不会被编译
三、python代码注释基础
Python中使用#表示单行注释。单行注释可以作为单独的一行放在被注释代码行之上，也可以放在语句或表达式之后。如下例子：
name = 'xiaohong' # 单行注释
# 单行注释
name = 'xiaohong'
Python中使用三个单引号或三个双引号表示多行注释。用在注释多写不下的情况，如下例子：
'''
这是使用三个单引号的多行注释
'''"""
这是使用三个双引号的多行注释
"""
四、DocStrings介绍与使用
4.1 DocStrings介绍
文档字符串
是一个重要工具，用于解释文档程序，帮助你的程序文档更加简单易懂
4.2 python中使用DocStrings
在函数体的第一行使用一对三个单引号 ''' 或者一对三个双引号 """ 来定义文档字符串。你可以使用 doc（注意双下划线）调用函数中的文档字符串属性。
编写示例如下：
def add(num1,num2): """ 完成传入的两个数之和 :param num1: 加数1 :param num2: 加数2 :return: 和 """ return num1 + num2 print( add.__doc__ )
备注：DocStrings 文档字符串使用惯例：它的首行简述函数功能，第二行空行，第三行为函数的具体描述。
五、DocStrings常用编写风格
5.1 reST风格
这是现在流行的一种风格，reST风格，Sphinx的御用格式，比较紧凑。
""" This is a reST style. :param param1: this is a first param :param param2: this is a second param :returns: this is a description of what is returned :raises keyError: raises an exception """
5.2 Google风格
""" This is a groups style docs. Parameters: param1 - this is the first param param2 - this is a second param Returns: This is a description of what is returned Raises: KeyError - raises an exception """
5.3 Numpydoc (Numpy风格)
"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
六、一些注释经验
- 注释不是越多越好。对于一目了然的代码，不需要添加注释。
- 对于复杂的操作，应该在操作开始前写上相应的注释。
- 对于不是一目了然的代码，应该在代码之后添加注释。
- 绝对不要描述代码。一般阅读代码的人都了解Python的语法，只是不知道代码要干什么
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持脚本之家。
相关文章
__builtins__ 是内建模块__builtin__中的对象,使用Python中的内建函数时会通过__builtins__引导,这里我们就来深入解析Python中的__builtins__内建对象,需要的朋友可以参考下2016-06-06
LyScript实现计算片段Hash并写出Excel的示例代码
本案例将学习运用LyScript计算特定程序中特定某些片段的Hash特征值，并通过xlsxwriter这个第三方模块将计算到的hash值存储成一个excel表格，感兴趣的可以跟随小编一起学习一下2022-09-09
天翼开放平台提供了一个免费的短信验证码API,下面看看使用方法吧,我们用python开发接口2013-12-12
在本篇文章里小编给大家整理的是一篇关于Python中Qslider控件实操详解内容，对此有兴趣的朋友们可以跟着学习参考下。2021-02-02
这篇文章主要介绍了Python采集某网站文档并保存word格式的示例,我们平常需要下载文档的时候，是不是发现，要么不能下载，要么不能复制，那么我们今天来分享一下，如何用Python将这些不给下载的文档给批量下载下来,需要的朋友可以参考下2023-07-07
这篇文章主要介绍了python实现图像处理之PiL依赖库的案例应用详解,本篇文章通过简要的案例,讲解了该项技术的了解与使用,以下就是详细内容,需要的朋友可以参考下2021-07-07
模拟退火算法不仅可以解决连续函数优化问题，KIRKPATRICK在1983年成功将其应用于求解组合优化问题,现已成为求解旅行商问题的常用方法，通常采用反序、移位和交换等操作算子产生新解2021-10-10
这篇文章主要为大家介绍了python Exception常规异常基类详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪2023-06-06
这篇文章主要为大家介绍了Python动态创建类实例详解,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪2023-12-12
这篇文章主要介绍了使用PyCharm调试程序实现过程，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2022-11-11
最新评论