Redis作者談如何編寫系統軟體的程式碼註釋

scripting.c：
    / *初始Stack：array* /
    lua_getglobal(lua,"table");
    lua_pushstring(lua,"sort");
    lua_gettable（LUA，-2）; / * Stack：array，table，table.sort * /
    lua_pushvalue（LUA，-3）; / * Stack：array，table，table.sort，array * /
    if（lua_pcall（lua，1,0,0））{
        / *Stack: array, table, error * /

        / *我們對錯誤不感興趣，我們假設如果
         *陣列中有'false'元素，那麼我們就再試驗
         *使用較慢的功能來處理這種情況，這個功能是
         *是：table.sort（table，__ redis__compare_helper）* /
        lua_pop(lua,1);             /* Stack: array, table */
        lua_pushstring(lua,"sort"); /* Stack: array, table, sort */
        lua_gettable(lua,-2);       /* Stack: array, table, table.sort */
        lua_pushvalue(lua,-3);      /* Stack: array, table, table.sort, array */
        lua_getglobal(lua,"__redis__compare_helper");
        /* Stack: array, table, table.sort, array, __redis__compare_helper */
        lua_call(lua,2,0);
    }

<p class="indent">

＃註釋分類

我隨機閱讀Redis原始碼時開始分類工作的，這樣檢查註釋在不同的上下文中是否有用，以及為什麼在這個上下文中有用。很快呈現的是註釋對於不同的動機原因有不同作用，它們在功能、寫作風格、長度和更新頻率方面表現的用處往往非常不同。

我最終進行了分類，在我的研究期間，我確定了九種註釋：

*函式註釋
*設計註釋
*為什麼註釋
*老師註釋
*清單註釋
*指南註釋
*細節註釋
*債務註釋
*備份註釋

在我看來，前六個主要是非常積極的註釋形式，而最後三個有點值得懷疑。在接下來的部分中，將使用Redis原始碼中的示例分析每種型別。

函式註釋

函式註釋的目標是防止讀者首先閱讀程式碼。在閱讀註釋之後，閱讀者應該可以將一些程式碼視為應遵守某些功能規則的黑盒子。通常，函式註釋位於函式定義的頂部，但它們可能位於其他位置，記錄類、宏或與其他函式隔離的程式碼塊，這些程式碼塊定義了某些介面。

rax.c：

    /* 在當前節點的子樹中尋找最新的金鑰。
     *記憶體不足返回0，否則返回1.對於下面的迭代函式這是不同的helper函式
    * /
    int raxSeekGreatest（raxIterator * it）{
    ...
<p class="indent">

設計註釋

雖然“函式註釋”通常位於函式的開頭，但設計註釋通常位於檔案的開頭。設計註釋基本上說明了當前程式碼的使用某些演算法，技術，技巧和實現的方式和原因。它是對程式碼中實現內容的更高階別概述。有了這樣的背景，閱讀程式碼會更簡單。此外，當我找到設計說明時，意味著可能有很多的程式碼。至少我知道在某些時候，在開發過程中發生了某種明確的設計階段。

根據我的經驗，設計註釋對於說明也非常有用，如果實現提出的解決方案看起來有點過於微不足道，那麼競爭的另外一個解決方案是什麼以及為什麼不採取另外一個？一般採取一個非常簡單的解決方案就足以滿足當前的要求。如果設計是正確的，閱讀者會說服自己當前的解決方案是合適的，這種簡單性來自一個過程，而不是懶惰或只知道如何編寫基本的東西。

bio.c：
     *設計
     * ------
     *
     *設計很簡單，我們有一個代表要執行作業的結構
     *以及的不同執行緒和代表每種不同作業型別的作業佇列。
     *每個執行緒都在等待佇列中的新作業，並順序處理每個作業
     *。
     ...
<p class="indent">

為什麼註釋

“為什麼註釋”解釋了程式碼執行某些操作的原因，即使程式碼執行的操作非常明確也要進行說明。請參閱Redis複製程式碼中的以下示例。

replication.c：

    if（idle> server.repl_backlog_time_limit）{
	/ *當我們釋放積壓backlog時，我們總是使用新的
	 *複製ID並清除ID2。這是必要的
	 *因為如果沒有積壓，master_repl_offset
	 *不會更新，但我們仍會保留我們的複製
	 * ID，導致以下問題：
	 *
	 * 1.我們是一個主節點例項。
	 * 2.我們的副節點會被提升為主人。它是repl-id-2，
	 *會與我們的repl-id相同。
	 * 3.我們作為主節點，會收到一些更新，但不會
	 *增加master_repl_offset。
	 * 4.稍後我們將變成副節點，連線到新的
	 *主節點，它透過複製ID將接受我們的PSYNC請求
	 *但會有資料不一致
	 *因為我們收到了寫操作。* /
	changeReplicationId（）;
	clearReplicationId2（）;
	freeReplicationBacklog（）;
	SERVERLOG（LL_NOTICE，
	    “％d秒後釋放複製backlog”
	    “沒有連線複製品。”，
	    （int）server.repl_backlog_time_limit）;
    }
<p class="indent">

老師註釋
教師註釋不會試圖解釋程式碼本身或我們應該注意的某些副作用。他們傳達程式碼有關領域知識（例如數學，計算機圖形學，網路，統計，複雜的資料結構），這可能是讀者技能組合之外的一個，或者只是太多的細節無法記住所有。

...

檢查清單註釋
這是一個非常常見和奇怪的問題：有時由於語言限制，設計問題，或者僅僅因為系統中出現的自然複雜性，不可能將所有包含的概念或介面集中在一個程式碼部分呈現，因此程式碼散落在各個地方，需要告訴讀者記住在當前程式碼的其他地方也有相關程式碼。一般概念是：

/ *警告：如果在此處新增型別ID，請務必修改
*函式getTypeNameByID（）也是如此。* /

指南註釋
Redis中的大多數註釋都是指南註釋。指南註釋正是大多數人認為完全無用的註釋。

指南註釋做了一件事：他們給讀者指路，在處理原始碼中的內容時協助他，幫助提供明確的劃分、節奏，並介紹需要要閱讀的內容。(類似老師註釋？)

指南註釋存在的唯一理由是降低程式設計師閱讀某些程式碼的認知負擔。

細節註釋
指南註釋是非常主觀的工具。你可能喜歡或不喜歡他們。我愛他們。然而，指南註釋可能會退化為一個非常糟糕的註釋：它很容易變成“細節註釋”。一個細節註釋應該也是一種指南註釋，其閱讀註釋的認知負荷與閱讀相關程式碼相同或更高。以下是一種細節註釋，很多書籍要求你避免的。

array_len ++; / *增加陣列的長度。* /

因此，如果你寫指南註釋，請確保你避免寫得太瑣碎，變成細節註釋。

債務註釋
如果原始碼本身內部有些硬編碼，那麼未來需要修正（嘗還債務），類似TODO，FIXME，XXX，“這裡一種駭客處理手法”，這些都是債務註釋的形式。

它們一般都不是很好，我試圖避免它們，但避免並不總是可能的，有時希望不要永遠忘記一個問題，我更喜歡在原始碼中放置一個標識。至少有一個人應該定期檢視這些註釋，看看是否可以將註釋放在更好的位置，或者該問題是否已不再相關或可以立即解決。

備份註釋
最後，備份註釋是開發人員註釋某些程式碼塊的舊版本甚至是整個函式的註釋，因為他或她對在新版本中執行的新更改感到不安全。令人費解的是，現在我們已經擁有Git卻仍然會發生這種情況。我想這是人們對丟失程式碼片段總是有一種不安的感覺，在一些多年的提交commit活動中，這種做法被認為更加理智或穩定。

總結
註釋可以作為分析工具。
註釋能提供程式碼片段的作用、確保它是什麼，有什麼副作用等要點。這通常是一個尋找錯誤的機會。在描述某些東西時很容易發現它有漏洞......如果你無法真正描述它，其實是因為你不能確定其行為：這種行為只是從複雜性中隨機出現。但是如果你真的不想出現這種情況，那麼你可以修復這個Bug。我覺得這是寫註釋的一個很好的理由。


＃編寫好的註釋比編寫好的程式碼更難
編寫註釋總要進行一些設計過程，並從更深層次的角度理解你正在編寫的程式碼。最重要的是，為了寫出好的註釋，你必須培養你的寫作技巧。相同的寫作技巧將幫助您編寫電子郵件，文件，設計文件，部落格文章和提交訊息。

Writing system software: code comments. - <antirez