国产欧美日韩灭亚洲精品,亚洲性人人天天夜夜摸,国产高清自拍视频

跨不同編程語言的注釋語法

外部代碼文檔通常是描述如何實(shí)現(xiàn)、運(yùn)行和配置代碼及其預(yù)期輸出的 README 文件。

API 文檔有時也稱為代碼文檔。我們的另一篇文章《如何編寫API文檔》對此進(jìn)行了更詳細(xì)的解釋)在這篇文章中，我們將重點(diǎn)介紹其他種類的代碼描述。

代碼注釋

代碼注釋（也稱為內(nèi)聯(lián)注釋）是描述代碼行或代碼塊的含義或作用的簡短說明。它們僅存在于源代碼文件中，對編譯器和瀏覽器不可見。下圖顯示了一段 JavaScript 代碼的注釋示例。

何時使用它們

代碼注釋對于解釋不明顯的事情很有用，例如

代碼塊的高級用途，
新穎或復(fù)雜的算法，
為什么選擇特定的（可能不理想的）解決方案，以及其他實(shí)施決策;和
TODO 和 FIXME 注釋，以提醒必須更改或改進(jìn)的內(nèi)容。

您還可以使用注釋語法在調(diào)試或開發(fā)期間暫時禁用代碼段，以便快速測試和迭代，正如您所記得的)，編譯不會看到標(biāo)記為注釋的行。

多行代碼注釋，解釋一段 JavaScript 代碼背后的實(shí)現(xiàn)決策

如何編寫代碼注釋

讓我們討論一些在代碼中編寫清晰有用的注釋的最佳實(shí)踐。

編寫自文檔化代碼。最好的代碼是自文檔化的——也就是說，它如此清晰和表達(dá)力強(qiáng)，幾乎不需要注釋進(jìn)行額外的解釋。下圖是一個可能難以理解的代碼示例。

下圖是自文檔化代碼的示例：函數(shù)和變量名稱清楚地傳達(dá)了它們的含義和用途。

確保您的注釋清晰易懂。撰寫簡潔、清晰且易于理解的注釋。除非必要并且在你的領(lǐng)域中廣為人知，否則避免使用行話。下圖是一個模糊且無用的代碼注釋示例。

下圖是詳細(xì)注釋的示例：它們解釋了代碼的作用，甚至提供了正在使用的公式。

解釋原因。雖然記錄代碼的作用和方式很重要，但解釋做出某些決定的原因可以為未來的開發(fā)人員（包括未來的自己）提供有價值的背景信息。給出架構(gòu)選擇、算法選擇，甚至是可能不明顯的具體代碼行背后的原因。

下面的圖片中的注釋沒有解釋為什么使用快速排序算法。它只是陳述了代碼的功能，這已經(jīng)是顯而易見的了。

相比之下，下圖中的注釋正確解釋了開發(fā)人員選擇快速排序算法的原因。

鏈接到外部代碼的原始源代碼。?在將來自外部源的代碼添加到項目時，提供鏈接非常重要。這種做法不僅給予原作者以認(rèn)可，還有助于其他人理解上下文并在需要時找到更多信息。包括源鏈接可以確保透明度并幫助維護(hù)代碼庫的完整性。

文檔字符串或文檔注釋

文檔注釋（Python 中的文檔字符串、Java 中的 javadoc 注釋等）提供了類、函數(shù)、方法和包的簡要摘要。理想情況下，它們應(yīng)該使讀者能夠掌握特定代碼塊的作用。

與代碼注釋類似，文檔字符串有助于保持代碼的可讀性。但是，盡管前者主要針對將維護(hù)和修改程序的開發(fā)人員，后者的預(yù)期受眾則是將使用項目并因此需要了解其不同元素如何工作的工程師。他們最有可能不是與源代碼交互，而是通過從文檔字符串生成的API或其他文檔進(jìn)行交互。

何時使用以及如何編寫文檔注釋

檔注釋應(yīng)伴隨每個模塊、函數(shù)、類和方法，這些是公共API的一部分。這種類型的注釋必須

以對象的用途的簡要描述開始——它應(yīng)該是遵循“做這件事”結(jié)構(gòu)的一句話；
提供關(guān)于代碼部分的詳細(xì)信息；
提及與片段相關(guān)的任何異常和限制。

例如，在定義一個函數(shù)時，文檔注釋應(yīng)該詳細(xì)說明它的參數(shù)、輸入和返回值、何時可以調(diào)用等。下圖顯示了 Python 中 square 函數(shù)的文檔字符串。

對于類，涵蓋其目的、行為、屬性和方法至關(guān)重要。反過來，每個方法也需要一個關(guān)于其用法、參數(shù)和副作用的文檔注釋。添加關(guān)于異常的注釋通知其他開發(fā)人員可能的錯誤情況以及如何適當(dāng)處理它們。

文檔生成器

每種語言都有其特定的工具，用于從文檔注釋中自動創(chuàng)建 HTML、PDF 或其他格式的 API 文檔：

Python的pydoc、pdoc或Sphinx；
Oracle的Java doc用于Java。像NetBeans、Eclipse和IntelliJ IDEA這樣的IDE內(nèi)置支持javadoc；
DocFX用于C#和其他.NET項目。以及
JavaScript的JSDoc。

雖然主要使用 Python，但 Sphinx 還支持 C++、JavaScript 和其他語言。或者，您也可以使用 Doxygen，這是一個與 C、C#、C++、Java、Python 和 PHP 兼容的開源平臺無關(guān)文檔生成器。請注意，文檔生成器僅限于它們在源代碼中遇到的注釋 — 它們無法添加除注釋之外的任何上下文或其他有用信息。

代碼文檔工具

今天，不同的工具可以幫助開發(fā)人員編寫代碼和文檔注釋。您可以直接在集成開發(fā)環(huán)境（IDE）或代碼編輯器中訪問此類助手，或者輕松地將它們作為擴(kuò)展添加。雖然數(shù)字助理不能為您完成所有代碼文檔工作，但它們可以節(jié)省大量時間。

代碼編輯器擴(kuò)展

許多 IDE 和代碼編輯器都附帶嵌入式工具、插件和擴(kuò)展，以改進(jìn)和簡化代碼文檔。例如，如果您使用 Visual Studio Code （VSCode），這是最流行的代碼編輯器之一，則可以利用 Better Comments 或 autoDocstring 等擴(kuò)展。

Better Comments將注釋分類為單行注釋、TODOs和其他組，使其更易于使用。該工具支持近 80 種編程語言。

使用 Better Comments VSCode 擴(kuò)展添加到代碼片段的注釋

autoDocstring 在 Python 中自動生成文檔注釋，提供各種文檔字符串樣式，包括 Google 和 Numpy 的樣式，并允許您自定義文檔字符串格式。

用生成式AI自動化代碼文檔

生成式 AI?工具正在成為開發(fā)人員日常生活的一部分。由大型語言模型驅(qū)動，可以幫助您解釋和記錄代碼。當(dāng)然，由AI產(chǎn)生的注釋和描述應(yīng)該手動檢查以確保準(zhǔn)確性和完整性。

GitHub Copilot 主要以其 AI 編碼功能而聞名，它還會生成內(nèi)聯(lián)注釋，解釋所選代碼片段的行為和用途。它作為 VS Code、Visual Studio、Neovim、JetBrains IDE 套件和 Azure Data Studio 的擴(kuò)展。

JetBrains AI Assistant是一個內(nèi)置于IDE的工具，由OpenAI模型驅(qū)動)，用于所有JetBrains開發(fā)環(huán)境，如Java和Kotlin的IntelliJ IDEA、Python和數(shù)據(jù)科學(xué)的PyCharm、.Net的ReSharper等。除了代碼補(bǔ)全和重構(gòu)外，助手還具有“編寫文檔”功能，以分析選定的類、函數(shù)或其他代碼段并為其生成注釋。

Mintlify Doc Writer?是一款 AI 驅(qū)動的文檔編寫器，支持 10+ 種語言和 9 種格式。要記錄一段代碼，你所要做的就是突出顯示一行或一塊代碼，然后點(diǎn)擊“生成文檔”按鈕。Mintlify Doc Writer僅作為VSCode或IntelliJ的擴(kuò)展提供。

由 Mintlify Doc Writer VSCode 擴(kuò)展自動生成的注釋

ChatGPT?是一種多功能工具，可應(yīng)用于各種用例，包括記錄代碼。你可以使用諸如“為以下代碼片段生成注釋”或更詳細(xì)的命令，例如“添加注釋以解釋算法背后的邏輯”或“添加描述函數(shù)的輸入?yún)?shù)和預(yù)期值的注釋”。

要使用 ChatGPT 記錄代碼，您可以將要描述的部分插入 ChatGPT 界面，或者如果有相應(yīng)的插件，則可以直接從開發(fā)環(huán)境訪問 AI。ChatGPT 擴(kuò)展的示例包括用于 AssistAI for Eclipse IDE、EasyCode ChatGPT for JetBrains IDEs、適用于VS code的ChatGPT擴(kuò)展等。

使用 ChatGPT 提示“為以下代碼片段生成注釋”添加到 JavaScript 代碼中的注釋

與上面提到的所有工具不同，ChatGPT 有助于生成我們將在下一節(jié)討論的 README 文件。

README 文件

README 文件是向用戶介紹您的軟件產(chǎn)品的文檔。它通常位于項目的根目錄中，當(dāng)人們訪問你的倉庫時，它是他們看到的第一個軟件描述。

每個軟件項目，無論其大小或復(fù)雜程度如何，都應(yīng)該有一個 README 文件。

但對于開源項目來說，這一點(diǎn)尤其重要。該文檔為潛在貢獻(xiàn)者提供有關(guān)項目目的的信息以及如何開始使用它的指南和貢獻(xiàn)指南。一個精心編寫的README文件可以是一個蓬勃發(fā)展的社區(qū)驅(qū)動型項目和一個難以獲得采用的項目之間的區(qū)別。

README 文件結(jié)構(gòu)

README 文件通常使用 markdown 編寫，markdown 是一種輕量級標(biāo)記語言，用于格式化純文本的樣式和結(jié)構(gòu)。該文件應(yīng)包含以下部分：

標(biāo)題 —— 項目的名稱和簡要說明。
描述 —— 項目的總結(jié)、其目的和主要功能。
目錄 —— README中的部分列表，鏈接到各自的標(biāo)題。
安裝說明，包括任何先決條件、依賴項、命令和配置需求。
使用說明，包括代碼示例、CLI命令或截圖來說明其功能。
功能，幫助讀者了解項目的能力。
貢獻(xiàn)指南，告知他人如何為項目做出貢獻(xiàn)。這包括提交問題、功能請求和拉取請求的指南。
許可證信息，這對開源項目至關(guān)重要。
致謝，涵蓋對項目中使用的第三方庫、工具或資源的致謝。
項目狀態(tài) —— 如果相關(guān)，提供有關(guān)項目當(dāng)前狀態(tài)的信息（例如，開發(fā)中、穩(wěn)定、已棄用）。

README 文件的確切結(jié)構(gòu)在很大程度上取決于項目的性質(zhì)以及它是供內(nèi)部使用還是開源。例如，內(nèi)部項目可能不需要貢獻(xiàn)和聯(lián)系信息部分。

如何創(chuàng)建 README

正如我們上面提到的，您可以利用 ChatGPT 來幫助您生成 README 文件。它們的質(zhì)量將取決于您創(chuàng)建的提示，以使AI理解你想要什么。閱讀我們關(guān)于提示工程的文章，了解如何有效地與 AI 交流。然而，還有一些其他更簡單的工具可以在處理 README 文件時節(jié)省你的時間。

Markdown 編輯器對于編寫和格式化 README 文件至關(guān)重要。它們具有易于使用的界面，并提供實(shí)時預(yù)覽、語法突出顯示、目錄生成、導(dǎo)出為 HTML、PDF 和其他格式等功能。值得考慮的優(yōu)秀 Markdown 編輯器包括 Typora、Dillinger 和 Obsidian。

README 生成器可自動創(chuàng)建這些文件，并提供模板和指導(dǎo)步驟。他們確保文檔包含所有必要的部分并遵循最佳實(shí)踐。最廣泛使用的 README 生成器之一是 readme.so，這是一種開源工具，提供交互式基于 Web 的編輯器、預(yù)構(gòu)建的部分和模板、實(shí)時預(yù)覽以及拖放部分重新排序。

代碼托管平臺主要用于協(xié)作、版本控制和在存儲庫中存儲代碼。但是，它們也支持 Markdown，使其適合直接在存儲庫中創(chuàng)建和管理 README 文件。例如，GitHub 提供了一個 Web 界面，用于直接在存儲庫中編輯和預(yù)覽 README 文件。此外，由于它支持版本控制，因此您可以使用它來跟蹤對 README 文件所做的更改以及這些更改的執(zhí)行者。