良好的注釋對于任何成功的Python項目來說都至關重要。在實際操作中，編寫注釋是一件困難且耗時費力的工作，因此一些開發(fā)人員并不喜歡這樣做。幸運的是，借助大型語言模型（LLMs）和像ChatGPT這樣的工具，您可以迅速為您的Python代碼和項目編寫注釋文檔。

Python中的注釋文檔寫作可以通過使用docstrings來實現，然后利用這些注釋來豐富項目的外部文檔。ChatGPT在編寫注釋和外部文檔方面非常有幫助。

在本教程中，您將學到以下內容：

• 如何使用不同的ChatGPT提示詞生成Python注釋
• 如何在使用ChatGPT生成注釋時采用不同的風格
• 如何在Python注釋中添加doctest測試

為了最大限度地利用本教程，你需要擁有一個ChatGPT賬戶，并且了解使用prompt engineering這個工具進行交互的基礎知識。同時，你還需要了解如何為Python代碼編寫文檔的基本知識。

使用ChatGPT為Python代碼編寫文檔的優(yōu)勢

對于任何軟件項目而言，擁有高質量且及時更新的文檔都是至關重要的。即使代碼庫寫得很好、項目的核心理念創(chuàng)新且有用，糟糕的文檔也可能導致項目的失敗或被忽視。

編寫良好的文檔需要耗費相當多的時間和精力。因此，借助ChatGPT這樣的大型語言模型(LLMs)來為你的項目和代碼提供適當的文檔，成為一種可行的替代方案。

使用ChatGPT為Python代碼編寫文檔的一些好處包括：

• 提高生產力：它可以自動化與代碼文檔及其維護相關的任務，從而節(jié)省大量的時間和精力。
• 提高質量：它有助于確保你的文檔準確、及時和全面。
• 提升用戶體驗：它可以生成引人入勝且用戶友好的文檔，為用戶帶來更好的體驗。
• 降低成本：它幫助降低了文檔創(chuàng)建和維護的成本。
• 提高合規(guī)性：它可以確保文檔符合標準和法規(guī)，使其更加一致和專業(yè)。

通過使用ChatGPT，你可以快速為你的Python代碼生成精美的文檔。在接下來的章節(jié)中，你將學習如何將ChatGPT作為助手，為你的Python項目創(chuàng)建一致的docstrings和用戶友好的外部文檔的基礎知識。

寫docstrings時可能用到的ChatGPT提示詞

在Python中，記錄代碼文檔的主要方式是使用docstrings。在Python中，docstring通常是一個用三引號括起來的字符串，位于模塊、函數、類和方法的第一行。Python會將這個字符串存儲在名為.__doc__的屬性中，以便對其進行特殊處理。

許多Python工具，包括代碼編輯器和集成開發(fā)環(huán)境（IDE），會利用docstrings在您編寫代碼時提供實時幫助。而且，docstrings還是Python內置的幫助系統(tǒng)的一部分，您可以使用help()函數來獲取相關幫助信息。

>>> help(str)

Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors is specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.
 |
 |  Methods defined here:
 |
 |  __add__(self, value, /)
 |      Return self+value.
 |
 |  __contains__(self, key, /)
 |      Return key in self.
...

在這個示例中，你調用help()函數并傳入str類作為參數，隨后你將獲得該類的文檔頁面，其中包含了該類的注釋。

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

在這種情況下，您可以通過直接訪問str類上的.__doc__屬性來獲取類的注釋。正如您可以得出的結論，注釋為您的代碼增加了很多價值。它們是您和其他Python開發(fā)人員用來了解任何Python對象的主要文檔。

當您使用類似Sphinx或MkDocs的工具構建項目文檔時，您還可以利用代碼的注釋。這些工具具有插件和功能，允許您提取注釋并將其作為項目外部文檔的一部分，這可以為您節(jié)省大量時間。

Python已經建立了編寫良好注釋的慣例。包、模塊、類、方法和函數的注釋都有具體的目標，并應遵循特定的指南。您可以在PEP 257中找到這些指南和約定。

盡管PEP 257提供了一個標準，但實際上在Python生態(tài)系統(tǒng)中，您會發(fā)現各種各樣的注釋風格。以下是一些常見的替代風格：

• Google風格注釋：這種風格來自Google，您會在該公司的開源項目中找到許多示例。
• NumPy注釋標準：這種風格是為NumPy庫開發(fā)的，許多其他Python項目也采用了它。
• reStructuredText（RST）或Sphinx注釋格式：這種風格基于reStructuredText，并來自Sphinx，這是一個用于自動化文檔創(chuàng)建的有用工具。
• Epytext風格：這是一種輕量級標記語言，用于格式化注釋，最初由Epydoc項目創(chuàng)建。每種風格都有自己的約定。通常，您應該選擇一種風格，并在整個Python項目中一致使用。

在實踐中，選擇注釋風格主要是個人偏好的問題。但是，您還應考慮項目的特定需求，包括以下特征：

• 項目的復雜性：如果您有一個龐大而復雜的項目，那么您可能會從Sphinx或NumPy風格中受益，因為它允許詳細的文檔。相比之下，小型項目可能只需要基本的文檔，像PEP 257或Google風格的注釋就足夠了。
• 文檔工具：如果您使用類似Sphinx或MkDocs的工具來生成項目的文檔，那么應選擇在您選擇的工具中具有最佳支持的風格。

有了對Python注釋的簡要背景，您現在可以開始引導ChatGPT為您編寫一些注釋了。

將目標代碼作為chatGPT提示詞的一部分使用

創(chuàng)建編寫注釋提示的最快方法是將目標代碼包含在提示本身的一部分?？紤]以下示例，您創(chuàng)建了一個用于生成將兩個數字相加的函數注釋的提示，以下是您和ChatGPT可能的對話：

您：為以下函數編寫一行注釋：

def add(a, b):
    return a + b

ChatGPT:

def add(a, b):
    """Return the sum of a and b."""
    return a + b

您：為以下函數編寫Google風格的注釋：

def add(a, b):
    return a + b

ChatGPT:

def add(a, b):
    """Sum two numbers.

    Args:
        a (int or float): The first number.
        b (int or float): The second number.

    Returns:
        int or float: The sum of the two numbers.
    """
    return a + b

您：為以下函數編寫NumPy風格的注釋：

def add(a, b):
    return a + b

ChatGPT:

def add(a, b):
    """
    Sum two numbers.

    Parameters
    ----------
    a : int or float
        The first number to be added.
    b : int or float
        The second number to be added.

    Returns
    -------
    int or float
        The sum of a and b.
    """
    return a + b

您：為以下函數編寫Sphinx風格的注釋：

def add(a, b):
    return a + b

ChatGPT:

def add(a, b):
    """
    Calculate the sum of two numbers.

    :param a: The first number.
    :type a: int or float
    :param b: The second number.
    :type b: int or float
    :return: The sum of the two numbers.
    :rtype: int or float
    """
    return a + b

這三個注釋看起來比您之前看到的單行注釋更完整、更精細。當您添加關于要使用的特定風格的信息時，ChatGPT可以為您的函數生成完整的注釋。當然，初始結果可能不是完美的，但這是一個很好的起點。

最重要的一點是，通過使用一個簡短的句子作為提示，您已經獲得了完整的注釋。這對于您的項目是一個令人難以置信的生產力提升。

ChatGPT不僅允許您為函數生成注釋，還可以處理模塊、類等等。以下是一個生成Circle類及其方法注釋的簡短示例：

您：為以下類及其方法編寫NumPy風格的注釋：

class Circle:
    def __init__(self, radius):
        self.radius = radius

    def calculate_area(self):
        return round(math.pi * self.radius ** 2, 2)

ChatGPT:

class Circle:
    """
    A Circle class to perform some circle-related operations.

    Parameters
    ----------
    radius : float
        The radius of the circle.

    Attributes
    ----------
    radius : float
        The radius of the circle.

    Methods
    -------
    calculate_area():
        Calculates the area of the circle.
    """

    def __init__(self, radius):
        """
        Constructs all the necessary attributes for the circle object.

        Parameters
        ----------
        radius : float
            The radius of the circle.
        """
        self.radius = radius

    def calculate_area(self):
        """
        Calculate the area of the circle.

        Returns
        -------
        float
            The area of the circle rounded to 2 decimal places.
        """
        return round(math.pi * self.radius ** 2, 2)

哇！太棒了！通過一個簡短的提示句子，您讓ChatGPT為您的類及其所有方法生成了NumPy風格的注釋。這是您代碼庫的一個很好的補充。

在提示詞中僅包含簽名

有時，您無法將目標代碼作為提示的一部分。這可能是由于隱私要求，或者您只是想保護公司的代碼安全。在這種情況下，您可以創(chuàng)建僅使用類、方法和函數簽名的提示。

關于ChatGPT使用數據的問題目前有很多正在進行的訴訟。無論如何，您都應該檢查ChatGPT的使用條款，以確保該工具適合您，并且您正在正確使用它。

要理解如何創(chuàng)建這些類型的提示，請考慮一個檢查數字是否落在給定區(qū)間內的函數的簽名：

您：為具有以下簽名的函數編寫Google風格的注釋：

def in_interval(number, start, end):

ChatGPT:

def in_interval(number, start, end):
    """
    Checks if a given number is within a specified interval.

    This function takes three arguments: a number, and the start
    and end points of an interval.
    It checks whether the given number falls within the specified
    interval or not.

    Args:
        number (int or float): The number to check.
        start (int or float): The starting point of the interval.
        end (int or float): The ending point of the interval.

    Returns:
        bool: True if the given number falls within the interval,
        False otherwise.

    Raises:
        ValueError: If the start is larger than the end, or if
        the number, start, or end are not numbers.
    """

在這個例子中，函數的簽名是您提供給ChatGPT的唯一上下文。LLM足夠智能，可以檢查函數的名稱和參數，并為您生成適當的注釋。請注意，在這種類型的提示中，具有描述性的函數和參數名稱至關重要。否則，輸出可能不夠好。

在大多數情況下，在函數的簽名中添加類型提示將提高生成的注釋的質量。

編寫不使用代碼的提示詞

您還可以通過僅描述代碼的輸入和輸出，或提供代碼功能的詳細描述來構建提示。同樣，在不允許將代碼作為提示的一部分上傳時，這些類型的提示是有用的。

為了說明，以下是一個提示，要求ChatGPT為一個確定整數是否為質數的函數編寫注釋：

您：為一個接受整數作為參數并確定它是否為質數的函數編寫Google風格的注釋。

ChatGPT:

def is_prime_number(n):
    """
    Determines if an input integer is a prime number.

    This function takes an integer as an argument and checks
    whether it is a prime number. A prime number is a
    positive natural number greater than 1 that has no positive
    integer divisors other than 1 and itself.

    Args:
        n (int): The integer to check.

    Returns:
        bool: True if the input integer is a prime number,
        False otherwise.

    Raises:
        ValueError: If n is less than or equal to 1.
    """

這個注釋非常完整和有用。它甚至包括了質數的解釋，這太棒了！您可以進一步調整并優(yōu)化一些細節(jié)。然而，您已經有了一個很好的起點。

在提示詞中詢問測試和用例

使用示例可能是良好軟件文檔的最重要部分。通過代碼示例，用戶可以快速了解如何使用您的代碼以及它的工作原理。通常，其他開發(fā)人員會瀏覽您的文檔，直到找到一個代碼示例。

因此，在您的注釋中添加使用示例是一個大加分項。通過ChatGPT，提供使用示例只是在提示中包含一個簡短句子的問題?？紤]以下提示及其輸出：

您：為以下函數編寫NumPy風格的注釋。添加一個包含使用示例的部分，作為doctest測試：

def add(a, b):
 return a + b

ChatGPT:

def add(a, b):
 """
 Add two numbers together.

 This function takes two numbers (either integers or floats)
 as arguments and returns their sum.

 Parameters
 ----------
 a : int or float
     The first number to add.
 b : int or float
     The second number to add.

 Returns
 -------
 int or float
     The sum of the two input numbers.

 Examples
 --------
 >>> add(1, 2)
 3
 >>> add(5.5, 2.5)
 8.0
 >>> add(100, -50)
 50
 """
 return a + b

突出顯示的行顯示了函數的使用示例。在提示中，您指示ChatGPT使用doctest測試格式進行示例。這將提供兩個重要的資產：

1、使用示例 

2、對代碼的基本測試

太棒了！您一舉獲得了兩個好處！您的文檔為用戶提供了很酷的使用示例，同時還有幫助您使代碼更健壯的測試。您可以使用doctest命令運行這些測試。

為您的Python代碼創(chuàng)建外部文檔

到目前為止，您已經使用ChatGPT幫助您為Python代碼編寫文檔字符串。盡管文檔字符串可能是項目文檔的重要部分，但可能不足夠。您的代碼中可能有一些方面需要更深入的解釋和詳細的示例。

因此，如果您想要擁有改善用戶與項目互動的優(yōu)秀文檔，那么您需要創(chuàng)建其他外部文檔，例如README文件、教程和操作指南。

創(chuàng)建這種類型的文檔將需要比為代碼創(chuàng)建文檔字符串更多的精力和時間。幸運的是，ChatGPT在這方面也可以幫助您。在接下來的幾節(jié)中，您將探討如何使用ChatGPT為Python項目創(chuàng)建外部文檔的基礎知識。首先，您將從README文件開始。

創(chuàng)建README文件

README文件可以說是您為任何Python項目創(chuàng)建的最基本的外部文檔之一。您可能會找到許多有關在README文件中包含什么的不同建議。總的來說，該文件的內容將取決于您具體的項目及其主要目標。

在為給定項目創(chuàng)建README文件時，您可以依賴ChatGPT。如果您對在這種類型的文件中包含什么沒有明確的想法，那么您可以詢問ChatGPT：

您：編寫README文件的推薦指南是什么？

ChatGPT：編寫一個良好的README文件對于幫助用戶了解您的項目的目的、如何使用以及如何潛在地為其做出貢獻是很重要的。以下是一些通常包含在寫得很好的README文件中的常見部分：

• 項目標題：README文件開頭的簡短、引人注目的標題。
• 項目描述：描述項目、它的功能以及它的目的的幾段文字。
• 安裝和入門：關于如何安裝項目和任何依賴項，如何設置它以及如何運行它的詳細說明。對于軟件項目，包括必要的命令行。
• 使用示例：展示如何使用項目的示例。在這一部分，代碼片段和截圖可能非常有用。
• 貢獻指南：如果您的項目是開源的，并且您接受貢獻，請說明如何貢獻和向項目提交拉取請求。您可能還包括代碼風格偏好、他們應該通過的自動測試等等。
• 許可證：注明項目的許可證類型。
• 聯系信息：提供您的聯系信息或獲取支持的指南。
• 致謝：在必要時，致謝相關工作或您使用的資源。

使您的README清晰、簡潔且信息豐富。記住，通常這是人們訪問您的項目時首次看到的東西，它可能極大地影響他們是否使用或為其做出貢獻的決定。

當然，這個列表并不是完整或確定的。根據您具體的項目，您可能需要一些其他部分。然而，輸出為創(chuàng)建一個出色的README文件提供了一個很好的起點。

現在，您可以選擇文件的最佳結構，然后為ChatGPT創(chuàng)建特定的提示，以幫助您編寫每個部分。首先從標題開始：

您：為一個提供基本數學運算的Python項目的README文件編寫五個引人入勝的標題。

ChatGPT：

• “歡迎來到PyBasicMath：Python中基本數學運算的一站式解決方案”
• “PyBasicMath：使用基本數學函數簡化復雜計算”
• “使用PyBasicMath輕松掌握數學：基本計算的完整Python包”
• “釋放數學的力量：PyBasicMath快速高效的Python數學運算”
• “PyBasicMath：讓數學變得易于接近，適用于各級別的Python開發(fā)者”

這是一份出色的標題建議清單。也許你已經對其中一些感興趣，但你還可以從這些建議中挑選一些點子，自行創(chuàng)作一個引人入勝的標題。繼續(xù)嘗試編寫提示，生成ChatGPT上方建議的其他部分，你將驚訝于ChatGPT在這方面的實用性。

作為練習，你可以嘗試逐步編寫具體的提示，以生成ChatGPT上建議的其他部分。

逐步向ChatGPT請求幫助逐段創(chuàng)建README文件，而不是一次性讓它生成整個README文件，可能更加便捷有效，因為你可以調整提示，專注于特定部分。

生成代碼解釋

ChatGPT可以生成對代碼工作原理的詳細解釋。這一功能為你創(chuàng)作外部文檔提供了很好的機會。以下是一個提示，要求語言模型解釋一個函數的運作方式：

你：解釋以下函數的運作方式：

def find_extremes(iterable):
    data = tuple(iterable)
    if len(data) == 0:
        raise ValueError("input iterable must not be empty")
    return min(data), max(data)

ChatGPT:

find_extremes(iterable)函數用于在可迭代對象（如列表、元組或任何其他Python可迭代對象）中查找最小和最大值。以下是逐步說明：

• data = tuple(iterable)：這行代碼將輸入的可迭代對象轉換為元組。無論輸入是列表、集合還是其他類型的可迭代對象，通過將其轉換為元組，確保數據可以在接下來的步驟中一致地進行迭代。
• if len(data) == 0: raise ValueError("input iterable must not be empty")：如果元組數據的長度為零（即輸入的可迭代對象為空），則引發(fā)一個帶有消息“input iterable must not be empty”的ValueError異常。這充當守衛(wèi)子句，防止函數處理空的可迭代對象，這將導致min和max函數也引發(fā)ValueError。
• return min(data), max(data)：這一行使用內置的Python函數min和max分別查找可迭代對象中的最小和最大值。這些值作為一個元組返回。

如果函數可以比較數據中的元素，則確定最小和最大值。如果不能（例如，可迭代對象是一個不實現比較操作的復雜對象），則min和max函數將引發(fā)TypeError。

總體而言，該函數接受任何可迭代對象，并返回一個表示可迭代對象中最小和最大值的元組。

ChatGPT的輸出非常詳細，逐行解釋了函數的工作原理。這段解釋將是項目外部文檔的很好補充。你可以將這個解釋用在教程、操作指南，甚至是README文件中，如果這適用于手頭的項目。

創(chuàng)建用例示例

你已經了解到，ChatGPT可以作為文檔字符串的一部分生成使用示例。它還可以生成你可以在教程、操作指南或README文件中使用的使用示例：

你：為以下函數編寫三個使用示例。對每個示例進行解釋：

def is_divisible(a, b):
    if not a % b:
        return True
    return False

ChatGPT:

is_divisible(a, b)函數用于檢查一個數字（a）是否能被另一個數字（b）整除。它使用模運算符（%），該運算符返回a除以b的余數。如果余數為0，則表示a能被b整除。

print(is_divisible(10, 5))  # Returns: True

在這個示例中，該函數正在檢查10是否能被5整除。由于10除以5的商為2，沒有余數，所以函數返回True。

print(is_divisible(17, 3))  # Returns: False

在這種情況下，該函數正在檢查17是否能被3整除。由于17除以3的商為5，余數為2，所以函數返回False。

print(is_divisible(36, 9))  # Returns: True

在這里，該函數檢查36是否能被9整除。由于36除以9的商為4，沒有余數，所以函數返回True。這表示36能被9整除。

請注意，你的提示包括你想要的具體示例數量。它還要求提供單獨的解釋。你還可以添加有關代碼其他方面的更詳細說明。例如，你可以詢問特定的邊緣情況，比如第二個參數為0時的情況。

詳細的說明將提高生成的輸出質量，并將解釋引導到代碼的具體和重要行為，這對你的用戶可能非常有用。

編寫教程和操作指南

既然你已經使用ChatGPT生成了代碼解釋和使用示例，你可以將它們組合起來，為你的代碼開發(fā)教程或操作指南。

例如，假設你想創(chuàng)建一個關于使用一個執(zhí)行基本數學計算的Python庫的教程。如果你已經使用一個ChatGPT線程為該庫生成了代碼示例和解釋，那么聊天已經有足夠的上下文來生成標題建議、大綱、介紹，甚至是一個良好的結論。

以下是一個短提示，要求ChatGPT為教程生成一個大綱：

你：為一個執(zhí)行基本數學計算的Python庫的教程寫一個大綱。

ChatGPT:

以下是一個基本數學計算的Python庫教程的大綱：

I. 介紹

介紹Python中基本數學計算的重要性
引言Python的數學計算庫的作用
提供教程的目標和預期受眾
II. 安裝與導入

安裝數學計算庫（例如，NumPy）
導入庫到Python腳本或Jupyter Notebook
III. 基本數學操作
A. 算術運算
1. 加法
2. 減法
3. 乘法
4. 除法
5. 取余
B. 數學函數
1. 平方根
2. 指數函數
3. 對數函數

IV. 數組和矩陣操作
A. 數組基礎
1. 創(chuàng)建數組
2. 訪問和修改元素
3. 數組切片
B. 數組運算
1. 數組加法和減法
2. 數組乘法和除法
C. 線性代數操作
1. 矩陣乘法
2. 行列式和逆矩陣

V. 統(tǒng)計和隨機數
A. 統(tǒng)計操作
1. 平均值
2. 中位數
3. 方差和標準差
B. 隨機數生成
1. 生成隨機數
2. 隨機抽樣

VI. 繪圖與可視化
A. 使用Matplotlib進行基本繪圖
1. 折線圖
2. 散點圖
B. 高級可視化（可選）
1. 熱圖
2. 3D圖

VII. 案例研究

結合以上所學，通過一個實際案例演示如何應用數學計算庫解決問題
VIII. 進階主題（可選）
A. 優(yōu)化和求解方程
1. 優(yōu)化問題
2. 方程求解

IX. 總結

總結主要概念和技能
鼓勵學習者進一步探索和應用所學知識
X. 參考文獻

列出使用到的Python庫和相關文檔的引用
這個大綱可以根據目標受眾的技能水平和需求進行調整。

現在，您可以為ChatGPT編寫具體的提示詞，以生成每個部分的內容。您還可以在相應的部分插入使用示例和代碼解釋。試試看吧！

正如您所見，ChatGPT在記錄Python項目方面是一個很好的伙伴。然而，在發(fā)布任何生成的內容之前，請確保對其進行全面的審查，以確保準確性和質量。

總結

現在，你知道如何利用像ChatGPT這樣的工具來使用適當的文檔字符串記錄你的代碼。你還學會了如何在ChatGPT的幫助下快速創(chuàng)建Python項目的外部文檔。

在這個教程中，你學會了如何：

• 有效編寫不同的ChatGPT提示以生成Python文檔字符串
• 在使用ChatGPT生成文檔字符串時采用不同的風格
• 要求ChatGPT為文檔字符串添加doctest測試和使用示例
• 使用ChatGPT構建Python項目的外部文檔

有了這些技能，你現在可以開始為你的Python代碼和項目創(chuàng)建有用且引人入勝的文檔。