建议4:在代码中适当添加注释

三种形式的代码注释介绍

有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.
---------------------------------------
"""

注释直接关系到代码的可读性和可维护性,同时它还能够帮助发现错误的藏身之处。 因为代码是说明你怎么做的,而好的注释能够说清楚你想做什么,它们相辅相成。 但往往有些程序员并不重视它,原因是多方面的

  1. 有人觉得程序的实现才是最重要的,至于注释是一件浪费时间的事情;
  2. 还有的人明明知道注释很重要,可是太懒,不愿意写或者随便应付;
  3. 也有人重视注释却不得要领,反而使其成为代码的一种累赘。

下面针对以上几个心态举几个实际中常见例子。

错误用法示例

示例一:代码即注释(不写注释)。没有注释的代码通常会给他人的阅读和理解带来一定困难,即使是自己写的代码,过一段时间再回头阅读可能也需要一定时间才能理解当初的思路。

>>> 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]

其他比较常见的问题还包括:

  1. 代码不断更新而注释却没有更新;
  2. 注释比代码本身还复杂繁琐;
  3. 将别处的注释和代码一起拷贝过来,但上下文的变更导致注释与代码不同步;
  4. 更有个别人将注释当做自己的娱乐空间从而留下个性特征等

这几种行为都是平时要注意避免的。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值