python 中的注释(annotations)

在读代码的时候，我们有时候会遇到别人的代码中定义函数时有以下的写法：

NB(注意): # 后面的部分表示输出结果。

第一种类型注释：函数定义中的注释

class Debug:
    def calculateSum(self, size: int) -> int:
        return sum(range(size))


if __name__ == "__main__":
    main = Debug()
    result = main.calculateSum(10)
    print(result)                   # 45      

我们可以看到这里的参数​

​size​

​​后面有一个冒号，并且紧跟着整型​

​int​

​​标识符，在括号外还有一个->箭头

并且也跟着一个整型标识符int，这究竟是什么意思呢？其实这是一种特殊的注释方式，为了让我们在使用装饰器等其他函数的时候事半功倍。箭头后面的​​

​int​

​​标识符告诉使用者，这个函数的返回值应当是一个整型的，​

​size​

​​后面的标识符告诉使用者这个函数的输入参数应该是整型的。并且对于​

​->​

​​后面的标识符我们可以使用​

​.__annotations__['return']​

​的方法进行获取，代码如下：

def f(x) -> int:
    return int(x)


if __name__ == "__main__": 
    print(f.__annotations__['return'])  # <class 'int'>      

我们可以看到​

​f.__annotations__['return']​

​​输出的结果​

​<class 'int'>​

​​，返回的正是我们的注释类型，此处的​

​f​

​​为所定义函数的名称。

我们再看一个例子：

def calculateSum(x:'annotating x', y: 'annotating y', z: int) -> float: print(x + y + z)


if __name__ == "__main__": 
    calculateSum(5,6,7)                             # 18
    print(calculateSum.__annotations__['return'])   # <class 'float'>      

我们可以看到此时我们给予函数中的三个参数对用的注释，​

​x​

​​,​

​y​

​​均为字符串类型的注释，​

​z​

​​为整数类型的注释，最终当我们给予​

​x​

​​,​

​y​

​​,​

​z​

​​均为整数类型的数据时，获取了最后的结果​

​18​

​​，由此我们可以看到，对于​

​annotation​

​​，实际上是不影响真实的计算结果的，只是一种提示性的作用，因此要避免乱用。

而​​

​print(calculateSum.__annotations__['return'])​

​​的结果也得到了正确的返回值的注释类型。

实际上上述函数定义的代码也等同于，

def calculateSum(x:'annotating x', y: 'annotating y', z: int) -> float: 
    print(x + y + z)      

这种写法可能更符合我们的通用写法。

第二种注释：行间注释

代码如下：

class Debug:
    def __init__(self):
        self.x1 = 5
        self.x2 = 10
        
        
    def calculateSum(self):
        # print out the sum of these two numbers
        print(self.x1 + self.x2)


if __name__ == "__main__":
    main = Debug()
    main.calculateSum()      

如上述代码所示，​

​#​

​​后面的部分就是我们在​

​python​

​​中经常会用到的注释方法，也叫行间注释。如这里的​

​print out the sum of these two numbers​

​，这种注释不会通过外部命令被显示，只是用来告知或者提示阅读该代码的人下一行或者下一段代码所要实现的功能。

class Debug:
    """
    This is a class for debugging
    """
    def __init__(self):
        """
        This funtion only has one property
        """
        self.x = 5
        

main = Debug()