<ruby id="bdb3f"></ruby>

    <p id="bdb3f"><cite id="bdb3f"></cite></p>

      <p id="bdb3f"><cite id="bdb3f"><th id="bdb3f"></th></cite></p><p id="bdb3f"></p>
        <p id="bdb3f"><cite id="bdb3f"></cite></p>

          <pre id="bdb3f"></pre>
          <pre id="bdb3f"><del id="bdb3f"><thead id="bdb3f"></thead></del></pre>

          <ruby id="bdb3f"><mark id="bdb3f"></mark></ruby><ruby id="bdb3f"></ruby>
          <pre id="bdb3f"><pre id="bdb3f"><mark id="bdb3f"></mark></pre></pre><output id="bdb3f"></output><p id="bdb3f"></p><p id="bdb3f"></p>

          <pre id="bdb3f"><del id="bdb3f"><progress id="bdb3f"></progress></del></pre>

                <ruby id="bdb3f"></ruby>

                ThinkChat2.0新版上線,更智能更精彩,支持會話、畫圖、視頻、閱讀、搜索等,送10W Token,即刻開啟你的AI之旅 廣告
                注釋雖然寫起來很痛苦, 但對保證代碼可讀性至關重要. 下面的規則描述了如何注釋以及在哪兒注釋. 當然也要記住: 注釋固然很重要, 但最好的代碼本身應該是自文檔化. 有意義的類型名和變量名, 要遠勝過要用注釋解釋的含糊不清的名字. 你寫的注釋是給代碼讀者看的: 下一個需要理解你的代碼的人. 慷慨些吧, 下一個人可能就是你! ## 7.1. 注釋風格 > Tip > 使用 `//` 或 `/* */`, 統一就好. `//` 或 `/* */` 都可以; 但 `//`_更_ 常用. 要在如何注釋及注釋風格上確保統一. ## 7.2. 文件注釋 > Tip > 在每一個文件開頭加入版權公告, 然后是文件內容描述. 法律公告和作者信息: 每個文件都應該包含以下項, 依次是: > > - 版權聲明 (比如, `Copyright 2008 Google Inc.`) > - 許可證. 為項目選擇合適的許可證版本 (比如, Apache 2.0, BSD, LGPL, GPL) > - 作者: 標識文件的原始作者. 如果你對原始作者的文件做了重大修改, 將你的信息添加到作者信息里. 這樣當其他人對該文件有疑問時可以知道該聯系誰. 文件內容: 緊接著版權許可和作者信息之后, 每個文件都要用注釋描述文件內容. 通常, `.h` 文件要對所聲明的類的功能和用法作簡單說明. `.cc` 文件通常包含了更多的實現細節或算法技巧討論, 如果你感覺這些實現細節或算法技巧討論對于理解 `.h` 文件有幫助, 可以該注釋挪到 `.h`, 并在 `.cc` 中指出文檔在 `.h`. 不要簡單的在 `.h` 和 `.cc` 間復制注釋. 這種偏離了注釋的實際意義. ## 7.3. 類注釋 > Tip > 每個類的定義都要附帶一份注釋, 描述類的功能和用法. // Iterates over the contents of a GargantuanTable. Sample usage: // GargantuanTable_Iterator* iter = table->NewIterator(); // for (iter->Seek("foo"); !iter->done(); iter->Next()) { // process(iter->key(), iter->value()); // } // delete iter; class GargantuanTable_Iterator { ... }; 如果你覺得已經在文件頂部詳細描述了該類, 想直接簡單的來上一句 “完整描述見文件頂部” 也不打緊, 但務必確保有這類注釋. 如果類有任何同步前提, 文檔說明之. 如果該類的實例可被多線程訪問, 要特別注意文檔說明多線程環境下相關的規則和常量使用. ## 7.4. 函數注釋 > Tip > 函數聲明處注釋描述函數功能; 定義處描述函數實現. 函數聲明: 注釋位于聲明之前, 對函數功能及用法進行描述. 注釋使用敘述式 (“Opens the file”) 而非指令式 (“Open the file”); 注釋只是為了描述函數, 而不是命令函數做什么. 通常, 注釋不會描述函數如何工作. 那是函數定義部分的事情. 函數聲明處注釋的內容: > > - 函數的輸入輸出. > - 對類成員函數而言: 函數調用期間對象是否需要保持引用參數, 是否會釋放這些參數. > - 如果函數分配了空間, 需要由調用者釋放. > - 參數是否可以為 `NULL`. > - 是否存在函數使用上的性能隱患. > - 如果函數是可重入的, 其同步前提是什么? 舉例如下: > > > // Returns an iterator for this table. It is the client's // responsibility to delete the iterator when it is done with it, // and it must not use the iterator once the GargantuanTable object // on which the iterator was created has been deleted. // // The iterator is initially positioned at the beginning of the table. // // This method is equivalent to: // Iterator* iter = table->NewIterator(); // iter->Seek(""); // return iter; // If you are going to immediately seek to another place in the // returned iterator, it will be faster to use NewIterator() // and avoid the extra seek. Iterator* GetIterator() const; 但也要避免羅羅嗦嗦, 或做些顯而易見的說明. 下面的注釋就沒有必要加上 “returns false otherwise”, 因為已經暗含其中了: > > > // Returns true if the table cannot hold any more entries. bool IsTableFull(); 注釋構造/析構函數時, 切記讀代碼的人知道構造/析構函數是干啥的, 所以 “destroys this object” 這樣的注釋是沒有意義的. 注明構造函數對參數做了什么 (例如, 是否取得指針所有權) 以及析構函數清理了什么. 如果都是些無關緊要的內容, 直接省掉注釋. 析構函數前沒有注釋是很正常的. 函數定義: 每個函數定義時要用注釋說明函數功能和實現要點. 比如說說你用的編程技巧, 實現的大致步驟, 或解釋如此實現的理由, 為什么前半部分要加鎖而后半部分不需要. _不要_ 從 `.h` 文件或其他地方的函數聲明處直接復制注釋. 簡要重述函數功能是可以的, 但注釋重點要放在如何實現上. ## 7.5. 變量注釋 > Tip > 通常變量名本身足以很好說明變量用途. 某些情況下, 也需要額外的注釋說明. 類數據成員: 每個類數據成員 (也叫實例變量或成員變量) 都應該用注釋說明用途. 如果變量可以接受 `NULL` 或 `-1` 等警戒值, 須加以說明. 比如: > > > private: // Keeps track of the total number of entries in the table. // Used to ensure we do not go over the limit. -1 means // that we don't yet know how many entries the table has. int num_total_entries_; 全局變量: 和數據成員一樣, 所有全局變量也要注釋說明含義及用途. 比如: > > > // The total number of tests cases that we run through in this regression test. const int kNumTestCases = 6; ## 7.6. 實現注釋 > Tip > 對于代碼中巧妙的, 晦澀的, 有趣的, 重要的地方加以注釋. 代碼前注釋: 巧妙或復雜的代碼段前要加注釋. 比如: > > > // Divide result by two, taking into account that x // contains the carry from the add. for (int i = 0; i < result->size(); i++) { x = (x << 8) + (*result)[i]; (*result)[i] = x >> 1; x &= 1; } 行注釋: 比較隱晦的地方要在行尾加入注釋. 在行尾空兩格進行注釋. 比如: > > > // If we have enough memory, mmap the data portion too. mmap_budget = max<int64>(0, mmap_budget - index_->length()); if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) return; // Error already logged. 注意, 這里用了兩段注釋分別描述這段代碼的作用, 和提示函數返回時錯誤已經被記入日志. 如果你需要連續進行多行注釋, 可以使之對齊獲得更好的可讀性: > > > DoSomething(); // Comment here so the comments line up. DoSomethingElseThatIsLonger(); // Comment here so there are two spaces between // the code and the comment. { // One space before comment when opening a new scope is allowed, // thus the comment lines up with the following comments and code. DoSomethingElse(); // Two spaces before line comments normally. } NULL, true/false, 1, 2, 3...: 向函數傳入 `NULL`, 布爾值或整數時, 要注釋說明含義, 或使用常量讓代碼望文知意. 例如, 對比: > > > Warning > > bool success = CalculateSomething(interesting_value, 10, false, NULL); // What are these arguments?? 和: > > > bool success = CalculateSomething(interesting_value, 10, // Default base value. false, // Not the first time we're calling this. NULL); // No callback. 或使用常量或描述性變量: > > > const int kDefaultBaseValue = 10; const bool kFirstTimeCalling = false; Callback *null_callback = NULL; bool success = CalculateSomething(interesting_value, kDefaultBaseValue, kFirstTimeCalling, null_callback); 不允許: 注意 _永遠不要_ 用自然語言翻譯代碼作為注釋. 要假設讀代碼的人 C++ 水平比你高, 即便他/她可能不知道你的用意: Warning // 現在, 檢查 b 數組并確保 i 是否存在, // 下一個元素是 i+1. ... // 天哪. 令人崩潰的注釋. ## 7.7. 標點, 拼寫和語法 > Tip > 注意標點, 拼寫和語法; 寫的好的注釋比差的要易讀的多. 注釋的通常寫法是包含正確大小寫和結尾句號的完整語句. 短一點的注釋 (如代碼行尾注釋) 可以隨意點, 依然要注意風格的一致性. 完整的語句可讀性更好, 也可以說明該注釋是完整的, 而不是一些不成熟的想法. 雖然被別人指出該用分號時卻用了逗號多少有些尷尬, 但清晰易讀的代碼還是很重要的. 正確的標點, 拼寫和語法對此會有所幫助. ## 7.8. TODO 注釋 > Tip > 對那些臨時的, 短期的解決方案, 或已經夠好但仍不完美的代碼使用 `TODO` 注釋. `TODO` 注釋要使用全大寫的字符串 `TODO`, 在隨后的圓括號里寫上你的大名, 郵件地址, 或其它身份標識. 冒號是可選的. 主要目的是讓添加注釋的人 (也是可以請求提供更多細節的人) 可根據規范的 `TODO` 格式進行查找. 添加 `TODO` 注釋并不意味著你要自己來修正. > > > // TODO(kl@gmail.com): Use a "*" here for concatenation operator. // TODO(Zeke) change this to use relations. 如果加 `TODO` 是為了在 “將來某一天做某事”, 可以附上一個非常明確的時間 “Fix by November 2005”), 或者一個明確的事項 (“Remove this code when all clients can handle XML responses.”). ## 譯者 (YuleFox) 筆記 1. 關于注釋風格,很多 C++ 的 coders 更喜歡行注釋, C coders 或許對塊注釋依然情有獨鐘, 或者在文件頭大段大段的注釋時使用塊注釋; 1. 文件注釋可以炫耀你的成就, 也是為了捅了簍子別人可以找你; 1. 注釋要言簡意賅, 不要拖沓冗余, 復雜的東西簡單化和簡單的東西復雜化都是要被鄙視的; 1. 對于 Chinese coders 來說, 用英文注釋還是用中文注釋, it is a problem, 但不管怎樣, 注釋是為了讓別人看懂, 難道是為了炫耀編程語言之外的你的母語或外語水平嗎; 1. 注釋不要太亂, 適當的縮進才會讓人樂意看. 但也沒有必要規定注釋從第幾列開始 (我自己寫代碼的時候總喜歡這樣), UNIX/LINUX 下還可以約定是使用 tab 還是 space, 個人傾向于 space; 1. TODO 很不錯, 有時候, 注釋確實是為了標記一些未完成的或完成的不盡如人意的地方, 這樣一搜索, 就知道還有哪些活要干, 日志都省了.
                  <ruby id="bdb3f"></ruby>

                  <p id="bdb3f"><cite id="bdb3f"></cite></p>

                    <p id="bdb3f"><cite id="bdb3f"><th id="bdb3f"></th></cite></p><p id="bdb3f"></p>
                      <p id="bdb3f"><cite id="bdb3f"></cite></p>

                        <pre id="bdb3f"></pre>
                        <pre id="bdb3f"><del id="bdb3f"><thead id="bdb3f"></thead></del></pre>

                        <ruby id="bdb3f"><mark id="bdb3f"></mark></ruby><ruby id="bdb3f"></ruby>
                        <pre id="bdb3f"><pre id="bdb3f"><mark id="bdb3f"></mark></pre></pre><output id="bdb3f"></output><p id="bdb3f"></p><p id="bdb3f"></p>

                        <pre id="bdb3f"><del id="bdb3f"><progress id="bdb3f"></progress></del></pre>

                              <ruby id="bdb3f"></ruby>

                              哎呀哎呀视频在线观看