2015-09-02 50 views
1

我有一個通用的文檔字符串格式,我在製作函數時試圖遵循這些格式。我給出了這個函數做了什麼總結,然後簡要說明了它輸入什麼類以及輸出什麼類。爲某些python函數傳輸文檔字符串

def cuberoot4u(number): 
    """Returns the cube root of number. 

    cuberoot4u(float) -> float 

    """ 
    return pow(number, 1/3) 

因此,在這種情況下,cuberoot4u爲輸入獲取一個浮點數並返回一個用於輸出的浮點數。

如何以文檔形式最好地向用戶傳達函數需要什麼類輸入,如果它需要.txt文件作爲輸入並輸出字符串中的內容?

def getText(filename): 
    """Reads the file filename and returns the content. 

    getText(?????) -> str 
    """ 
    fd = open(filename) 
    text = fd.read() 
    fd.close() 
    return text 

難道是最好說getText(filename.txt) -> str或者是有一個特定的類名是很像的字符串是「STR」和一個整數是「廉政」?

另外,關於其輸出不象本實施例中清楚地定義的函數什麼:

def commandmenu(): 
    """Begin some random menu which does stuff. 

    commandmenu() -> ?????? 
    """ 


    while 1: 
     someuserinput = input("Enter a command: ") 
     if someuserinput == 'this': 
      pass 
     elif someuserinput == 'that': 
      pass 
     else: 
      print('u suck') 
    return None 

因此,在這種情況下,存在進入的功能沒有初始輸出,因爲它導致一個來自用戶的輸入在它做某事之前。什麼最適合?????如果這樣的功能變得越來越細緻,並且可能導致多種不同的輸出,這取決於對用戶的提示等等。

回答

2

你碰到什麼通常被稱爲在抽象洞中。在你的情況下,抽象是指定參數類型的每個函數都足以記錄它。大多數語言(或者可能全部)和Python尤其沒有足夠強大的類型系統來實現它。

考慮類似於您的第一個功能,但計算平方根:

def squareroot4u(number): 
    """Returns the cube root of number. 

    squareroot4u(float) -> float 

    """ 
    return pow(number, 1/2) 

顯然,返回類型爲float只有number非負,否則就應該是complex。 Python的(不像一些科學爲導向的語言)並沒有對非負數獨立的類型,因此必須另行指定contract強制執行它:

def squareroot4u(number): 
    """Returns the cube root of number. 

    squareroot4u(number: float) -> float 

    precondition: number >= 0 
    raises ValueError otherwise 
    """ 
    return pow(number, 1/2) 

我個人使用Sphinx的記錄,並在其格式它看起來像

def squareroot4u(number): 
    """Returns the cube root of number. 

    :param number: a non-negative number, raises ``ValueError`` otherwise 
    :type number: ``float`` 
    :return: square root of the input 
    :rtype: ``float`` 
    """ 
    return pow(number, 1/2) 

對於你的第二個功能:

def getText(filename): 
    """Reads the file filename and returns the content. 

    :param filename: a path to a text file 
        (raises ``WhateverError``/blows ups the monitor otherwise) 
    :type filename: ``str`` 
    :returns: file contents 
    :rtype: ``str`` 
    """ 

注意,類型在Python當從上下文中推斷文檔時,文檔串往往被省略(例如,還有什麼比其他可strfilename?)

現在與第三功能,除了類型和合同,你有副作用。這些應該記錄在函數的一般描述中(如果它們是運行此函數的主要觀點),或者在註釋/警告中(如果它們只是要記住的東西)。例如(使用再次Sphinx語法):

def commandmenu(): 
    """Begin some random menu which does stuff. 
    Shows an input prompt and awaits user input. 

    .. warning:: 

     May or may not randomly format your hard drive during full moon. 
    """ 

在其他語言(例如,Haskell中),一些副作用可以被表示爲類型(單子)和靜態檢查。例如,有一個類似的功能,以您的getText在具有類型

readFile :: FilePath -> IO String 

而不僅僅是String,這將意味着它在它的參數一些純操作(即,始終返回標準庫對於相同的輸入相同的輸出並且沒有副作用)。

相關問題