三种形式的代码注释介绍
有3种形式的代码注释:块注释、行注释以及文档注释(docstring)。
1. 行注释(Line Comments):用于注释单行代码,以 # 开头,其后的内容会被 Python 解释器忽略。
# 这是一个行注释
x = 5 # 这是另一个行注释,跟在代码后面
- 可单独占一行,或放在代码行的末尾。
- 常用于解释单行代码的功能、参数含义或临时禁用代码。
2. 块注释(Block Comments):用于注释多行内容,注释较大的代码段或算法逻辑,通常用 多个 # 开头,每行单独注释。
# 这是一个块注释
# 它可以跨越多行
# 常用于解释复杂代码段或函数逻辑
- 每行以 # 开头,不依赖缩进。
- 适用于注释较大的代码块(如函数、类或循环体)。
3. 文档注释(Docstrings):用于为 模块、函数、类或方法 添加文档说明,使用 三引号(""" 或 ''') 包裹。
def function_name(arg1, arg2):
"""函数的文档字符串(Docstring)
第一行:简要描述函数功能
后续行:详细说明参数、返回值和其他信息
"""
# 函数体
return result
- 可通过 __doc__ 属性访问,也能被工具(如 help())自动提取生成文档。
- 遵循特定格式规范(如 Google 风格、NumPy 风格 或 reStructuredText)。
具体什么是Google风格下面有举例。
三种注释用法的补充
这3种形式的惯用法大概有如下几种:
1)使用块或者行注释时仅仅注释那些复杂的操作、算法,还有别人难以理解的技巧或者不够一目了然的代码。
2)注释和代码隔开一定的距离,同时在块注释之后最好多留几行空白再写代码。下面两行代码显然(1)代码的阅读性要好。
>>> x=0
>>> x=x+1 # increace x by 1 (1)
>>> x=x+1# incredse x by 1 (2)
3) 给外部可访问的函数和方法(无论是否简单)添加文挡注释。
注释要清楚地描述方法的功能,并对参数、返回值以及可能发生的异常进行说明,使得外部调用它的人员仅仅看docstring就能正确使用。较为复杂的内部方法也需要进行注释。推荐的函数注释如下(Google风格):
def FuncName(parameterl ,parameter2):
"""Describe what this function does.
#such as "Find whether the special string is in the queue or not"
Args :
parameterl: parameter typer what is this parameter used for,
# such as strqueue:stringfstring queue list for search
parameter2: parameter typer what is this parameter used for.
#such as str: string, string to find
Returns:
return type, return value,
#such as boolean,^epcial string found return Truefelse return False
"""
print('function body')
print(FuncName.__doc__) # 输出上述函数的文档注释
4)推荐在文件头中包含copyright申明、模块描述等,如有必要,可以考虑加入作者信息以及变更记录。
"""
Licensed Materials - Property of CorpA
(C) Copyright A Corp. 1999, 2011 All Rights Reserved
CopyRight statement and purpose...
---------------------------------------
File Name : comments.py
Description. : description what the main function of this file
Author: Author name
Change Activity:
list the change activity and time and author information.
---------------------------------------
"""
注释直接关系到代码的可读性和可维护性,同时它还能够帮助发现错误的藏身之处。 因为代码是说明你怎么做的,而好的注释能够说清楚你想做什么,它们相辅相成。 但往往有些程序员并不重视它,原因是多方面的
- 有人觉得程序的实现才是最重要的,至于注释是一件浪费时间的事情;
- 还有的人明明知道注释很重要,可是太懒,不愿意写或者随便应付;
- 也有人重视注释却不得要领,反而使其成为代码的一种累赘。
下面针对以上几个心态举几个实际中常见例子。
错误用法示例
示例一:代码即注释(不写注释)。没有注释的代码通常会给他人的阅读和理解带来一定困难,即使是自己写的代码,过一段时间再回头阅读可能也需要一定时间才能理解当初的思路。
>>> a=3
>>> n=5
>>> count,sn,tn = 1,0, 0
>>> while count<=n:
>>> tn+=a
>>> sn+=tn
>>> a*=10
>>> count+=1
>>> print (sn)
37035
示例二:注释与代码重复。注释应该是用来解释代码的功能、原因以及想法的,而不是对代码本身的解释。
>>> # coding=utf-8
>>> print ("please input number n")
>>> n=input()
>>> print ("please input number m:")
>>> m=input()
>>> t=int(n)/2 # t是n的一芈
>>> #循环.条件为t*m/n小于n
>>> while(t*int(m)/(int(n)+1) < int(n)):
>>> t=0.5*int(m)+int(n)/20 # 重新计算 t 值
>>> print (t)
>>> break
please input number n
4
please input number m:
5
2.7
示例三:利用注释语法快速删除代码。对于不再需要的代码,应该将其删除,而不是将其注释掉。即使你担心以后还会用到,版本控制工具也可以让你轻松找问被删除的代码。
>>> x=2
>>> y=5
>>> z=3
>>> """following code is no longer needed since there is a better way
>>> if x>y:t=x;x=y;y=t
>>> if x>z:t=z;z=x;x=t
>>> if y>z:t=y;y=z;z=t
>>> print "the order from small to big is: %d %d %d" % (x,y,z)
>>> """
>>> order_list=[x,y,z]
>>> order_list.sort()
>>> print(order_list)
[2, 3, 5]
其他比较常见的问题还包括:
- 代码不断更新而注释却没有更新;
- 注释比代码本身还复杂繁琐;
- 将别处的注释和代码一起拷贝过来,但上下文的变更导致注释与代码不同步;
- 更有个别人将注释当做自己的娱乐空间从而留下个性特征等
这几种行为都是平时要注意避免的。