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()