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初学之用户登录的实现过程(实例讲解)
Dec 23 Python
Window10+Python3.5安装opencv的教程推荐
Apr 02 Python
如何使用Python的Requests包实现模拟登陆
Apr 27 Python
Python中fnmatch模块的使用详情
Nov 30 Python
python模拟登陆,用session维持回话的实例
Dec 27 Python
Python实现SQL注入检测插件实例代码
Feb 02 Python
对Django中static(静态)文件详解以及{% static %}标签的使用方法
Jul 28 Python
Python实现图片裁剪的两种方式(Pillow和OpenCV)
Oct 30 Python
Python PyInstaller库基本使用方法分析
Dec 12 Python
Python用input输入列表的实例代码
Feb 07 Python
Python使用urllib模块对URL网址中的中文编码与解码实例详解
Feb 18 Python
python使用gdal对shp读取,新建和更新的实例
Mar 10 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在XP下IIS和Apache2服务器上的安装
2006/09/05 PHP
php生成WAP页面
2006/10/09 PHP
php实现给图片加灰色半透明效果的方法
2014/10/20 PHP
PHP数组与对象之间使用递归实现转换的方法
2015/06/24 PHP
Laravel中日期时间处理包Carbon的简单使用
2017/09/21 PHP
PHP按一定比例压缩图片的方法
2018/10/12 PHP
JMenuTab简单使用说明
2008/03/13 Javascript
javascript TextArea动态显示剩余字符
2008/10/22 Javascript
Jquery知识点一 Jquery的ready和Dom的onload的区别
2011/01/15 Javascript
javascript 弹出窗口中是否显示地址栏的实现代码
2011/04/14 Javascript
javascript动态向网页中添加表格实现代码
2014/02/19 Javascript
jquery.idTabs 选项卡使用示例代码
2014/09/03 Javascript
JavaScript获得页面base标签中url的方法
2015/04/03 Javascript
JavaScript对象数组如何按指定属性和排序方向进行排序
2016/06/15 Javascript
AngularJS学习笔记(三)数据双向绑定的简单实例
2016/11/08 Javascript
div实现自适应高度的textarea实现angular双向绑定
2017/01/08 Javascript
使用live-server快速搭建本地服务器+自动刷新的方法
2018/03/09 Javascript
JS中的回调函数实例浅析
2018/03/21 Javascript
详解如何使用webpack打包JS
2018/06/21 Javascript
使用iView Upload 组件实现手动上传图片的示例代码
2018/10/01 Javascript
详解一个基于套接字实现长连接的express
2019/03/28 Javascript
Python读取MRI并显示为灰度图像实例代码
2018/01/03 Python
Python+tkinter使用80行代码实现一个计算器实例
2018/01/16 Python
详解Python中的分组函数groupby和itertools)
2018/07/11 Python
python leetcode 字符串相乘实例详解
2018/09/03 Python
在Python文件中指定Python解释器的方法
2019/02/18 Python
Python脚本利用adb进行手机控制的方法
2019/07/08 Python
Python timeit模块的使用实践
2020/01/13 Python
Python Tornado批量上传图片并显示功能
2020/03/26 Python
Python JSON常用编解码方法代码实例
2020/09/05 Python
python 统计list中各个元素出现的次数的几种方法
2021/02/20 Python
外贸公司实习自我鉴定
2013/09/24 职场文书
社区中秋节活动方案
2014/01/29 职场文书
《只有一个地球》教学反思
2014/02/14 职场文书
建筑安全生产目标责任书
2014/07/23 职场文书
java Nio使用NioSocket客户端与服务端交互实现方式
2021/06/15 Java/Android