Python代码注释规范代码实例解析
一、代码注释介绍
- 注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。
- 注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。
- 在有处理逻辑的代码中，源程序有效注释量必须在20％以上。
二、代码注释分类
行注释：在符号后那一行不会被编译（显示）
块注释：被块注释符号中间的部分不会被编译
三、python代码注释基础
Python中使用#表示单行注释。单行注释可以作为单独的一行放在被注释代码行之上，也可以放在语句或表达式之后。如下例子：
name='xiaohong'#单行注释
#单行注释
name='xiaohong'
Python中使用三个单引号或三个双引号表示多行注释。用在注释多写不下的情况，如下例子：
'''
这是使用三个单引号的多行注释
'''"""
这是使用三个双引号的多行注释
"""
四、DocStrings介绍与使用
4.1DocStrings介绍
文档字符串
是一个重要工具，用于解释文档程序，帮助你的程序文档更加简单易懂
4.2python中使用DocStrings
在函数体的第一行使用一对三个单引号'''或者一对三个双引号"""来定义文档字符串。你可以使用doc（注意双下划线）调用函数中的文档字符串属性。
编写示例如下：
defadd(num1,num2): """完成传入的两个数之和 :paramnum1:加数1 :paramnum2:加数2 :return:和 """ returnnum1+num2 print(add.__doc__)
备注：DocStrings文档字符串使用惯例：它的首行简述函数功能，第二行空行，第三行为函数的具体描述。
五、DocStrings常用编写风格
5.1reST风格
这是现在流行的一种风格，reST风格，Sphinx的御用格式，比较紧凑。
""" ThisisareSTstyle. :paramparam1:thisisafirstparam :paramparam2:thisisasecondparam :returns:thisisadescriptionofwhatisreturned :raiseskeyError:raisesanexception """
5.2Google风格
""" Thisisagroupsstyledocs. Parameters: param1-thisisthefirstparam param2-thisisasecondparam Returns: Thisisadescriptionofwhatisreturned Raises: KeyError-raisesanexception """
5.3Numpydoc(Numpy风格)
"""
Mynumpydocdescriptionofakind
ofveryexhautivenumpydocformatdocstring.
Parameters
----------
first:array_like
the1stparamname`first`
second:
the2ndparam
third:{'value','other'},optional
the3rdparam,bydefault'value'
Returns
-------
string
avalueinastring
Raises
------
KeyError
whenakeyerror
OtherError
whenanothererror
"""
六、一些注释经验
- 注释不是越多越好。对于一目了然的代码，不需要添加注释。
- 对于复杂的操作，应该在操作开始前写上相应的注释。
- 对于不是一目了然的代码，应该在代码之后添加注释。
- 绝对不要描述代码。一般阅读代码的人都了解Python的语法，只是不知道代码要干什么
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持毛票票。
声明：本文内容来源于网络，版权归原作者所有，内容由互联网用户自发贡献自行上传，本网站不拥有所有权，未作人工编辑处理，也不承担相关法律责任。如果您发现有涉嫌版权的内容，欢迎发送邮件至：czq8825#qq.com（发邮件时，请将#更换为@）进行举报，并提供相关证据，一经查实，本站将立刻删除涉嫌侵权内容。