thumb 包含註釋的 Arduino 程式碼片段 在計算機語言中，註釋是計算機語言的一個重要組成部分，用於在原始碼中解釋程式碼的功用，可以增強程式的可讀性，可維護性，或者用於在原始碼中處理不需執行的程式碼段，來除錯程式的功能執行。 註釋在隨原始碼進入預處理器或編譯器處理後會被移除，不會在目的碼中保留其相關資訊。 使用 怎麼用註釋是一個備受爭論的論題，觀點是各種各樣的，有時候甚至觀點是正相反的。寫法也是各種各樣，有時候意見也是存在矛盾的。 程式碼設計和審查 註釋可以用於提供虛擬碼的大綱，並根據該大綱編寫程式碼。透過這種形式，程式碼的邏輯會更加清晰。 反向迴圈所有從服務獲取的元素 他們應該按照時間順序執行 for i numElementsReturned 1 i 0 i 處理每一個元素裡的資料 updatePattern i returnedElements i 如果在提交程式碼時，註釋沒有被刪除，那麼程式碼審查者可以根據註釋比較程式碼和意圖的擬合度。一個常見的誤解 理解程式碼想要做什麼是很簡單的事情。 程式碼描述 註釋可用於程式碼內容的總結、表達開發者的意圖。持該觀點的學者認為，用更為簡單的英語去解釋程式碼是多餘的。 需要重新解釋地程式碼，可能意味是候程式碼太複雜，這時候需要去重寫或者重新命名。 不要去解釋說明質量低下的程式碼，應該去重寫。Dont document bad code rewrite it The Elements of Programming Style Kernighan Plauger 好的註釋不應該去重複程式碼的內容、解釋程式碼，而是應該去解釋它的意圖。你應該嘗試在一個高的維度，將程式碼抽象出來，併為此說明。Good comments dont repeat the code or explain it They clarify its intent Comments should explain at a higher level of abstraction than the code what youre trying to do Code Complete McConnell 註釋也可用於解釋一個 zhcn 程式碼塊；zhtw 程式碼區塊；zhhk 程式碼區塊 有什麼缺陷，為什麼不是最好的方案。這對專案相當緊張、修正 bug 尤其有效。例如： Second variable dim because of server errors produced when reuse form data No documentation available on server behavior issue so just coding around it vtx servermappath local settings 值得注意的是，上述內容是針對英語國家的程式設計師。而在非英語國家裡，通過當地語言去解釋程式碼、翻譯程式碼的意思，這種行為是很常見的，也普遍被接受的。 演算法描述 比如，下面程式將增加一個註釋來解釋為什麼插入排序沒有被快速排序所替代，即使理論上前者比後者更慢。這將寫為如下： list f b f b f c f d f a Need a stable sort Besides the performance really does not matter insertion_sort list 元資料和資源 在註釋中，可以插入各種資源和元資料。 常見的資源有：圖示、流程圖、版權。 常見的元資料有：維護者、第一版的時間、編輯者、相關文件的連結等。 下面是 Spring 框架中的一段註釋，用於表達版權。 Copyright 20022016 the original author or authors Licensed under the Apache License Version 20 the License you may not use this file except in compliance with the License You may obtain a copy of the License at httpswwwapacheorglicensesLICENSE20 Unless required by applicable law or agreed to in writing software distributed under the License is distributed on an AS IS BASIS WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND either express or implied See the License for the specific language governing permissions and limitations under the License 許多程式碼維護者會將指導（元資料）放到註釋中，幫助讀者更好的閱讀，並提供反饋途徑。但值得一提，隨著 Git 等版本管理器的流行，元資料作為指導的功能也被部分代替了，如：Git 能記錄第一版程式碼、程式碼創作者、修改者等資訊。 除錯 程式設計師常用的技巧之一，透過暫時把程式碼塊註釋的方式，讓部分程式碼不執行。程式設計師透過該方式，尋找程式碼 bug 的位置。 文件自動生成 一些開發工具透過註釋來生成文件。如 java 程式透過 javadoc cc 等透過 doxygen 生成文件。 功能程式碼 作為程式碼的一部分被使用。如：條件註釋、Shebang。 種類與格式 註釋可分類為： 風格（行 塊） 解釋規則（忽略 插入 記憶體儲存） 遞迴（支援 不支援） 行註釋 行註釋透過使用換行 n 字元來指示註釋結束，以及使用標記來開始一條註釋。例： 符號 語言 C Fortran 77 C 必須在一行的第一個字元。 REM BASIC COMMANDCOM bash 、Perl、Python、Ruby、Windows PowerShell、PHP、Maple TeX Prolog MATLAB Erlang 、Visual Prolog Pascal ActionScript、C99、C、ObjectiveC、Swift、C、Go Object Pascal Delphi，Java、JavaScript、PHP Visual Basic、VBScript、REALbasic Fortran Basic Plus AutoHotkey、Autoit、Lisp、Scheme many assemblers Euphoria、Haskell、SQL、Ada、AppleScript、Eiffel、Lua、VHDL COBOL many assemblers Curl Vim 指令碼 Forth 批處理 塊註釋 塊註釋透過定義一個註釋開始和一個註釋結束標記來使用。在上下文中，空格和換行字元不作為區分標誌。例： 符號 語言 co co comment comment ALGOL 68 ActionScript AutoHotkey C C ObjectiveC Swift C Go Java JavaScript PHP PLI SQL Visual Prolog CSS Cobra Python Ruby Python begin cut Perl begin end Ruby tag tag SLang Haskell Object Pascal DelphiML Mathematica Pascal Applescript OCaml Maple Object Pascal DelphiPascal HTML、XML Curl MATLAB Lisp Lua if 0 endif C 語言 C zhhans 註釋；zhhant 註釋 參考文獻 Category 計算機語言 Category 帶有程式碼示例的條目