Python代码注释规范代码实例解析


Posted in Python onAugust 14, 2020

一、代码注释介绍

  • 注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码。
  • 注释是编写程序时,写程序的人给一个语句、程序段、函数等的解释或提示,能提高程序代码的可读性。
  • 在有处理逻辑的代码中,源程序有效注释量必须在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的语法,只是不知道代码要干什么

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持三水点靠木。

Python 相关文章推荐
python解析xml文件实例分享
Dec 04 Python
python pdb调试方法分享
Jan 21 Python
Python实现的数据结构与算法之快速排序详解
Apr 22 Python
Python常用库推荐
Dec 04 Python
利用Python脚本实现ping百度和google的方法
Jan 24 Python
Python操作SQLite数据库的方法详解
Jun 16 Python
python中kmeans聚类实现代码
Feb 23 Python
python3判断url链接是否为404的方法
Aug 10 Python
浅谈Python3 numpy.ptp()最大值与最小值的差
Aug 24 Python
pytorch 数据处理:定义自己的数据集合实例
Dec 31 Python
python标准库OS模块函数列表与实例全解
Mar 10 Python
python自动生成sql语句的脚本
Feb 24 Python
Python发送邮件实现基础解析
Aug 14 #Python
Python压缩模块zipfile实现原理及用法解析
Aug 14 #Python
Python编写memcached启动脚本代码实例
Aug 14 #Python
Python自动巡检H3C交换机实现过程解析
Aug 14 #Python
基于python调用jenkins-cli实现快速发布
Aug 14 #Python
使用tensorflow进行音乐类型的分类
Aug 14 #Python
10行Python代码实现Web自动化管控的示例代码
Aug 14 #Python
You might like
如何写php程序?
2006/12/08 PHP
jquery 应用代码 方便的排序功能
2010/02/06 Javascript
js实现touch移动触屏滑动事件
2015/04/17 Javascript
BootStrap实用代码片段之一
2016/03/22 Javascript
js判断所有表单项不为空则提交表单的实现方法
2016/09/09 Javascript
详解JavaScript中的属性和特性
2016/12/08 Javascript
微信小程序Server端环境配置详解(SSL, Nginx HTTPS,TLS 1.2 升级)
2017/01/12 Javascript
用vue和node写的简易购物车实现
2017/04/25 Javascript
浅谈vue中改elementUI默认样式引发的static与assets的区别
2018/02/03 Javascript
详解 vue better-scroll滚动插件排坑
2018/02/08 Javascript
详解Vue的钩子函数(路由导航守卫、keep-alive、生命周期钩子)
2018/07/24 Javascript
vue+Element实现搜索关键字高亮功能
2019/05/28 Javascript
小程序input数据双向绑定实现方法
2019/10/17 Javascript
用JS实现选项卡
2020/03/23 Javascript
python将多个文本文件合并为一个文本的代码(便于搜索)
2011/03/13 Python
使用python将mdb数据库文件导入postgresql数据库示例
2014/02/17 Python
python读取二进制mnist实例详解
2017/05/31 Python
python requests post多层字典的方法
2018/12/27 Python
windows下numpy下载与安装图文教程
2019/04/02 Python
Python with用法:自动关闭文件进程
2019/07/10 Python
python创建属于自己的单词词库 便于背单词
2019/07/30 Python
python实现高斯(Gauss)迭代法的例子
2019/11/20 Python
Python代码块及缓存机制原理详解
2019/12/13 Python
Python如何执行精确的浮点数运算
2020/07/31 Python
python 字符串格式化的示例
2020/09/21 Python
德国自行车商店:Tretwerk
2019/06/21 全球购物
医学检验专业大学生求职信
2013/11/18 职场文书
委托书模板
2014/04/04 职场文书
电教室标语
2014/06/20 职场文书
党支部群众路线整改措施思想汇报
2014/10/10 职场文书
个人工作作风整改措施思想汇报
2014/10/13 职场文书
2014年监理工作总结范文
2014/11/17 职场文书
应届毕业生求职信范文
2015/03/19 职场文书
2015庆祝七一建党节94周年活动总结
2015/03/20 职场文书
超市督导岗位职责
2015/04/10 职场文书
Mysql数据库命令大全
2021/05/26 MySQL