2024年七大最佳免費貨幣轉換API
外部代碼文檔通常是描述如何實現、運行和配置代碼及其預期輸出的 README 文件。
API 文檔有時也稱為代碼文檔。我們的另一篇文章《如何編寫API文檔》對此進行了更詳細的解釋)在這篇文章中，我們將重點介紹其他種類的代碼描述。
代碼注釋（也稱為內聯注釋）是描述代碼行或代碼塊的含義或作用的簡短說明。它們僅存在于源代碼文件中，對編譯器和瀏覽器不可見。下圖顯示了一段 JavaScript 代碼的注釋示例。
代碼注釋對于解釋不明顯的事情很有用，例如
您還可以使用注釋語法在調試或開發期間暫時禁用代碼段，以便快速測試和迭代，正如您所記得的)，編譯不會看到標記為注釋的行。
讓我們討論一些在代碼中編寫清晰有用的注釋的最佳實踐。
編寫自文檔化代碼。最好的代碼是自文檔化的——也就是說，它如此清晰和表達力強，幾乎不需要注釋進行額外的解釋。下圖是一個可能難以理解的代碼示例。
下圖是自文檔化代碼的示例：函數和變量名稱清楚地傳達了它們的含義和用途。
確保您的注釋清晰易懂。撰寫簡潔、清晰且易于理解的注釋。除非必要并且在你的領域中廣為人知，否則避免使用行話。下圖是一個模糊且無用的代碼注釋示例。
下圖是詳細注釋的示例：它們解釋了代碼的作用，甚至提供了正在使用的公式。
解釋原因。雖然記錄代碼的作用和方式很重要，但解釋做出某些決定的原因可以為未來的開發人員（包括未來的自己）提供有價值的背景信息。給出架構選擇、算法選擇，甚至是可能不明顯的具體代碼行背后的原因。
下面的圖片中的注釋沒有解釋為什么使用快速排序算法。它只是陳述了代碼的功能，這已經是顯而易見的了。
相比之下，下圖中的注釋正確解釋了開發人員選擇快速排序算法的原因。
鏈接到外部代碼的原始源代碼。?在將來自外部源的代碼添加到項目時，提供鏈接非常重要。這種做法不僅給予原作者以認可，還有助于其他人理解上下文并在需要時找到更多信息。包括源鏈接可以確保透明度并幫助維護代碼庫的完整性。
文檔注釋（Python 中的文檔字符串、Java 中的 javadoc 注釋等）提供了類、函數、方法和包的簡要摘要。理想情況下，它們應該使讀者能夠掌握特定代碼塊的作用。
與代碼注釋類似，文檔字符串有助于保持代碼的可讀性。但是，盡管前者主要針對將維護和修改程序的開發人員，后者的預期受眾則是將使用項目并因此需要了解其不同元素如何工作的工程師。他們最有可能不是與源代碼交互，而是通過從文檔字符串生成的API或其他文檔進行交互。
檔注釋應伴隨每個模塊、函數、類和方法，這些是公共API的一部分。這種類型的注釋必須
例如，在定義一個函數時，文檔注釋應該詳細說明它的參數、輸入和返回值、何時可以調用等。下圖顯示了 Python 中 square 函數的文檔字符串。
對于類，涵蓋其目的、行為、屬性和方法至關重要。反過來，每個方法也需要一個關于其用法、參數和副作用的文檔注釋。添加關于異常的注釋通知其他開發人員可能的錯誤情況以及如何適當處理它們。
每種語言都有其特定的工具，用于從文檔注釋中自動創建 HTML、PDF 或其他格式的 API 文檔：
雖然主要使用 Python，但 Sphinx 還支持 C++、JavaScript 和其他語言。或者，您也可以使用 Doxygen，這是一個與 C、C#、C++、Java、Python 和 PHP 兼容的開源平臺無關文檔生成器。請注意，文檔生成器僅限于它們在源代碼中遇到的注釋 — 它們無法添加除注釋之外的任何上下文或其他有用信息。
今天，不同的工具可以幫助開發人員編寫代碼和文檔注釋。您可以直接在集成開發環境 （IDE） 或代碼編輯器中訪問此類助手，或者輕松地將它們作為擴展添加。雖然數字助理不能為您完成所有代碼文檔工作，但它們可以節省大量時間。
許多 IDE 和代碼編輯器都附帶嵌入式工具、插件和擴展，以改進和簡化代碼文檔。例如，如果您使用 Visual Studio Code （VSCode），這是最流行的代碼編輯器之一，則可以利用 Better Comments 或 autoDocstring 等擴展。
Better Comments將注釋分類為單行注釋、TODOs和其他組，使其更易于使用。該工具支持近 80 種編程語言。
autoDocstring 在 Python 中自動生成文檔注釋，提供各種文檔字符串樣式，包括 Google 和 Numpy 的樣式，并允許您自定義文檔字符串格式。
生成式 AI?工具正在成為開發人員日常生活的一部分。由大型語言模型驅動，可以幫助您解釋和記錄代碼。當然，由AI產生的注釋和描述應該手動檢查以確保準確性和完整性。
GitHub Copilot 主要以其 AI 編碼功能而聞名，它還會生成內聯注釋，解釋所選代碼片段的行為和用途。它作為 VS Code、Visual Studio、Neovim、JetBrains IDE 套件和 Azure Data Studio 的擴展。
JetBrains AI Assistant是一個內置于IDE的工具，由OpenAI模型驅動)，用于所有JetBrains開發環境，如Java和Kotlin的IntelliJ IDEA、Python和數據科學的PyCharm、.Net的ReSharper等。除了代碼補全和重構外，助手還具有“編寫文檔”功能，以分析選定的類、函數或其他代碼段并為其生成注釋。
Mintlify Doc Writer?是一款 AI 驅動的文檔編寫器，支持 10+ 種語言和 9 種格式。要記錄一段代碼，你所要做的就是突出顯示一行或一塊代碼，然后點擊“生成文檔”按鈕。Mintlify Doc Writer僅作為VSCode或IntelliJ的擴展提供。
ChatGPT?是一種多功能工具，可應用于各種用例，包括記錄代碼。你可以使用諸如“為以下代碼片段生成注釋”或更詳細的命令，例如“添加注釋以解釋算法背后的邏輯”或“添加描述函數的輸入參數和預期值的注釋”。
要使用 ChatGPT 記錄代碼，您可以將要描述的部分插入 ChatGPT 界面，或者如果有相應的插件，則可以直接從開發環境訪問 AI。ChatGPT 擴展的示例包括用于 AssistAI for Eclipse IDE、EasyCode ChatGPT for JetBrains IDEs、適用于VS code的ChatGPT擴展等。
與上面提到的所有工具不同，ChatGPT 有助于生成我們將在下一節討論的 README 文件。
README 文件是向用戶介紹您的軟件產品的文檔。它通常位于項目的根目錄中，當人們訪問你的倉庫時，它是他們看到的第一個軟件描述。
每個軟件項目，無論其大小或復雜程度如何，都應該有一個 README 文件。
但對于開源項目來說，這一點尤其重要。該文檔為潛在貢獻者提供有關項目目的的信息以及如何開始使用它的指南和貢獻指南。一個精心編寫的README文件可以是一個蓬勃發展的社區驅動型項目和一個難以獲得采用的項目之間的區別。
README 文件通常使用 markdown 編寫，markdown 是一種輕量級標記語言，用于格式化純文本的樣式和結構。該文件應包含以下部分：
README 文件的確切結構在很大程度上取決于項目的性質以及它是供內部使用還是開源。例如，內部項目可能不需要貢獻和聯系信息部分。
正如我們上面提到的，您可以利用 ChatGPT 來幫助您生成 README 文件。它們的質量將取決于您創建的提示，以使AI理解你想要什么。閱讀我們關于提示工程的文章，了解如何有效地與 AI 交流。然而，還有一些其他更簡單的工具可以在處理 README 文件時節省你的時間。
Markdown 編輯器對于編寫和格式化 README 文件至關重要。它們具有易于使用的界面，并提供實時預覽、語法突出顯示、目錄生成、導出為 HTML、PDF 和其他格式等功能。值得考慮的優秀 Markdown 編輯器包括 Typora、Dillinger 和 Obsidian。
README 生成器可自動創建這些文件，并提供模板和指導步驟。他們確保文檔包含所有必要的部分并遵循最佳實踐。最廣泛使用的 README 生成器之一是 readme.so，這是一種開源工具，提供交互式基于 Web 的編輯器、預構建的部分和模板、實時預覽以及拖放部分重新排序。
代碼托管平臺主要用于協作、版本控制和在存儲庫中存儲代碼。但是，它們也支持 Markdown，使其適合直接在存儲庫中創建和管理 README 文件。例如，GitHub 提供了一個 Web 界面，用于直接在存儲庫中編輯和預覽 README 文件。此外，由于它支持版本控制，因此您可以使用它來跟蹤對 README 文件所做的更改以及這些更改的執行者。
以下是創建高質量代碼文檔時可以遵循的一些提示和最佳實踐。
在編寫代碼文檔之前，了解誰將閱讀它至關重要。考慮受眾的技術熟練程度和對代碼庫的熟悉程度。這將決定文檔所需的細節級別。
例如，與具有數十年經驗的專家相比，初學者開發人員需要更多細節和更簡單的術語。下圖顯示了適合專業 JavaScript 開發人員的代碼文檔。
下圖顯示了適合初學者 JavaScript 開發人員的代碼文檔。雖然時間較長，但這些觀眾會更容易理解。
將文檔集成到您的編碼流程中，這可能意味著：
編寫代碼時編寫文檔確保它準確反映你的思維過程和實現細節。
記錄你的代碼所做的任何前提條件或假設。這有助于其他開發人員了解他們需要具備什么才能有效使用你的代碼。
例如，下圖中項目的先決條件是 Python 版本 3.7 或更高版本、Numpy 版本 1.18 或更高版本以及 OpenCV 版本 4.2 或更高版本。負責代碼的開發人員還假定輸入圖像為 RGB 格式，并且已經過預處理以消除任何偽影或雜色。
Python 代碼包含先決條件信息的詳細信息
格式和樣式的一致性是創建專業代碼文檔的關鍵。
您可以通過為各種元素（如術語、語氣、結構、縮進、換行符、間距和文檔字符串格式）創建樣式指南來實現統一的代碼文檔。
雖然全面而徹底的文檔是必要的，但同樣重要的是要避免過多的注釋。當您提供過多、不必要或冗余的信息時，就會發生過度文檔編制，這些信息可能會使代碼變得混亂并使其更難閱讀。
解釋數組或變量是什么的過度文檔化和添加不必要的注釋的例子，因為大多數開發人員都熟悉這些概念。下面的圖像顯示了過度文檔化的代碼。
下圖顯示了僅包含相關信息的簡明代碼文檔。
文檔應隨著你的代碼演變。定期審查和更新你的文檔，以確保其保持準確和相關。你可以通過以下方式保持文檔更新：
遵循突出顯示的最佳實踐將使您能夠創建有效的代碼文檔，使您的代碼在將來更易于維護，并改善與其他開發人員的協作。
另外，請記住，好的文檔是一個隨著代碼的發展而發展的持續過程。養成編寫代碼時進行文檔記錄的習慣，您未來的自己和團隊成員會為此感謝您！
原文鏈接：https://www.altexsoft.com/blog/how-to-write-code-documentation/
