Python代码注释规范代码实例解析
作者:蓝 寅 发布时间:2023-03-15 04:59:56
一、代码注释介绍
注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码。
注释是编写程序时,写程序的人给一个语句、程序段、函数等的解释或提示,能提高程序代码的可读性。
在有处理逻辑的代码中,源程序有效注释量必须在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的语法,只是不知道代码要干什么
来源:https://www.cnblogs.com/dream66/p/12826947.html
猜你喜欢
- 文章主要讲术了一些SQL Server新的Bug,帮您认识这些被忽略的SQL Server注入技巧。1.关于Openrowset和Opend
- This is a {t}. {name}是一个很强大的字符串模板解析方法。它接受三个参数,分别是{args.text},{args.obj
- 今天研究了一下JS的用setAttribute方法实现一个页面两份样式表的效果,具体方法如下:第一步:在连接样式表的元素里定义一个id,例如
- 这篇论坛文章(赛迪网技术社区)详细的介绍了在MySQL中使用GRANT语句增添新用户的具体步骤,更多内容请参考下文…&
- 下表列出 SQL Server 查询分析器提供的所有键盘快捷方式。活动 快捷方式 书签:清除所有书签。 CTRL-SHIFT-F2
- 本文介绍了随机提取N条记录的例子,通过Sql server与access数据库的代码比较让你更快的掌握。随机提取10条记录的例子:Sql s
- 经常看到有新手问PHP有没有类似asp的left函数或right函数,实现截取某字符串左边或右边开始N个字符的函数。答案当然是有的。PHP中
- 代码如下:Select * from T_Employee select FName,FAge from T_Employee select
- 问题:如何把具有相同字段的记录删除,只留下一条。 例如:表test里有id,name字段,如果有name相同的记录只留下一条,
- SQL语句更改表所有者SQL语句更改表所有者单个修改所有者sql语句如下:查询分析器输入:EXEC sp_changeobject
- UNIX时间戳转换为日期用函数FROM_UNIXTIME()select FROM_UNIXTIME(1156219870);日期
- 文章中有不正确的或者说辞不清的地方,麻烦大家指出了~~~与PHP字符串转义相关的配置和函数如下: 1.magic_quotes_runtim
- 后台实时监控服务器的CUP与内存占用率的场景很常见,虽然没做过,但是着手写代码之前我真没想到会花2个多小时才最终实现。网上虽然搜 PHP C
- 1、下载安装MySQLdb类库http://www.djangoproject.com/r/python-mysql/2、修改setting
- 1. composer 安装 PDF组件composer require setasign/fpdicomposer require set
- 在使用Dreamweaver制作主页的时候往往需要改变表格的高度。然而有时当我们拖动表格的边框,无论怎样拖动,等到放下鼠标,表格却又恢复到原
- 当在设计中我们讨论到,对于一个功能或元素是否应该添加的时候,秉承“如无所需、勿增实体”的原则,我们通常会放弃只有小众/小部分人群才会使用的功
- 本文实例为大家分享了python实现学生管理系统的具体代码,供大家参考,具体内容如下一.面向过程版import osstu_list = [
- SQL语句先前写的时候,很容易把一些特殊的用法忘记,我特此整理了一下SQL语句操作,方便自己写SQL时方便一点,想贴上来,一起看看,同时希望
- 内容摘要:在本人上一篇教程《彻底弄懂CSS盒子模式五(定位强化练习) 》有讲到一个很酷的链接面板提示的实例制作,那时主要是用到di