obert C. Martin寫的《Clean Code》是我讀過的最好的編程書籍之一，若沒有讀過，推薦你將它加入書單。

注釋就意味著代碼無法自說明 —— Robert C. Martin

Martin在文中詳細討論了代碼注釋，我不會完全重復他的話。簡而言之，他的意思就是，這些注釋是注定會過時的。程序執行時會忽視注釋，所以無法保證這些說明注釋會準確的描述代碼作用。所以最好的方式是讓代碼自說明，如此，按照代碼邏輯，程序員和程序獲取到的信息是一致的。

思考如下代碼：

// Check to see if the employee is eligible for full benefits// 檢查員工是否有資格獲取全部福利if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) { …}

注釋有用么？當然有用，但下面的方式可能更好：

if (employee.isEligibleForFullBenefits()) { …}

代碼需要“言行一致”，注釋是能夠被命名良好的函數或變量取代的。Martin的意思并不是說永不使用注釋，而是應該盡量避免寫注釋，注釋就意味著代碼無法自說明。

那么對CSS而言呢？

我非常贊同Martin關于注釋的看法。當涉及到聲明式的語言如CSS時，就發現了一些有趣的地方。聲明式語言式必須符合對應格式的，而CSS選擇器基本是由HTML結構決定的。對這種代碼結構，我們能做的不多，這是否意味著CSS代碼必須注釋滿天飛？

額，也許吧。有很多的理由使用注釋，且注釋的寫法也有很多。讓我們來看一些注釋，思考這些注釋是否應該添加。先從答案顯然的開始吧，然后一步步深入到不那么好判斷的。

不好：多此一舉的注釋

任何語言，多此一舉的注釋都是多余的，如下的示例出自Bootstrap3的早期版本：

// Addressesaddress {…}

顯然，address是關于地址的選擇器

// Unordered and Ordered listsul,ol {…}

還有？

// Blockquotesblockquote {…}

趕緊停！

千萬不要寫那種注釋，趕緊刪掉這些多余的東西，它僅僅是在重復代碼而已。當然，新版本的Bootstrap已經刪除掉大部分多此一舉的無用注釋了。

不好： 塊分隔注釋

對CSS而言，塊分隔注釋是非常特殊的，如下：

/* ----------------- * TOOLTIPS * ----------------- */

這種注釋能把我逼瘋。我能想到為什么會寫下這種注釋：有時候我們的CSS會寫得非常長，當在超過千行的文件內查找時，就需要這種帶特殊標志的注釋來幫助快速搜索。

但事實上，很長很長的CSS文件已經不再流行了。若你的項目確實需要這種很大的CSS文件，它應該是由多個小的部分，通過CSS預處理工具組合而成的。

不好：解釋語法

又要用Bootstrap舉例了，以下代碼出自 _tooltips.scss:

// Allow breaking very long words so they don't overflow the tooltip's bounds// 設置長單詞換行word-wrap: break-word;

這種方式和“多此一舉的注釋”類似，注釋解釋word-wrap屬性的作用。這里有一篇文章講到這種注釋為什么不需要的原因，注釋應該解釋“為什么”，而不是“是什么”，即說明原因而不是說明作用（Why, not what）。

此處有一個例外，由于CSS有很多屬性，也許有些屬性是你完全不知道的，那么你用這種注釋是正常的。

不好：對庫進行介紹

如下是Bootstrap tooltips.scss文件的另一段注釋：

// Our parent element can be arbitrary since tooltips are by default inserted as a// sibling of their target element. So reset our font and text properties to avoid// inheriting weird values.// 由于提示框會被默認插入到目標元素后作為一個兄弟元素，// 所以需要重置提示框的字體屬性避免從父元素繼承樣式影響。@include reset-text();font-size: $font-size-sm;

這條注釋很有意思，看起來似乎并不違反“說明原因而不是說明作用？”規則，它表明由于可能會被一些意料之外的繼承字體屬性影響，所以用導入的方式來重置字體屬性。

但進一步來看，顯然在文件頭導入重置樣式的唯一的解釋就是擔心被繼承樣式影響。

所以，我認為這種注釋也是不需要的，因為導入函數名字已經說明用途了，盡量讓函數名切合作用，如reset-inherited-font或類似的名字，不僅清晰說明了用途還是說明了原因。這個是一個函數調用，函數名已經足夠解釋了。優先用這種方式來說明用途可以替代一些注釋。

CSS預處理器讓CSS更接近傳統編程語言。盡可能使用命名良好且有意義的變量和函數，這樣能讓代碼更清晰。

不好: 過時的注釋

.dropdown-header { … white-space: nowrap; // as with > li > a}

“as with > li > a”是什么意思？我第一反應就是也許在文件中還有一個> li > a的選擇器，而這行代碼就是指那個選擇器。也許文件中有一段注釋會專門解釋為何這樣寫，但我將文件重頭到尾都看了一邊，發現并沒有這個選擇器。文件只有一個.dropdown-item選擇器下有一個nowrap屬性，也許是就是指這個？或者也許這段注釋是指某行已經被刪除的代碼或引入其他文件中的代碼？若想要徹底弄清楚這個注釋的作用，唯一的方法就是翻遍整個git記錄了吧。

這是一個過時的注釋，也許它以前是有用的，但卻長時間沒有用到，所以過時了。這也許就是為什么Robert Martin對注釋的看法：若注釋對應的代碼更新了注釋就沒用了，甚至更糟糕，注釋可能會將你引到錯誤的方向。若發現這樣的注釋，一定要刪掉。它完全沒用，而且會浪費時間去思考到底有啥用？

有時有用的：有特殊意義的注釋

如下是一段帶注釋的代碼：

.dropdown-item { display: block; width: 100%; // For `<button>`s padding: $dropdown-item-padding-y $dropdown-item-padding-x; clear: both; font-weight: $font-weight-normal; color: $dropdown-link-color; text-align: inherit; // For `<button>`s white-space: nowrap; background: none; // For `<button>`s border: 0; // For `<button>`s}

這樣的注釋就是有用的，它們能告訴我們，這些特定的屬性是為覆蓋<button>樣式而寫的。這樣的注釋就是有用的，因為有時候代碼的意圖不是那么顯而易見的。

但此時也需要問一個問題：有什么辦法能讓代碼自說明呢？需要可以考慮將這些特定的屬性移到第二個選擇器中，專門為這些按鈕設置的選擇器。

.dropdown-item {
 display: block;
 padding: $dropdown-item-padding-y $dropdown-item-padding-x;
 clear: both;
 font-weight: $font-weight-normal;
 color: $dropdown-link-color;
 white-space: nowrap;
}
button.dropdown-item {
 width: 100%;
 text-align: inherit;
 background: none;
 border: 0;
}

這樣就非常清晰且易于理解，但副作用就是：專門增加了一個特殊的選擇器。

而相反，我認為這種方式非常利于使用mixin混入模式。重構為一個函數，該函數能在其他地方定義，并且讓代碼更清晰。考慮如下代碼：

.dropdown-item {
 @include remove-button-styles;
 display: block;
 width: 100%;
 padding: $dropdown-item-padding-y $dropdown-item-padding-x;
 clear: both;
 font-weight: $font-weight-normal;
 color: $dropdown-link-color;
 white-space: nowrap;
}

這段代碼沒有用任何注釋，但其功用很清晰，因為它使用的公用函數在其他模塊也能用到。我將width:100%保留下來而不是移到函數中，因為若將函數混和代碼時，width:100%可能會引起一些其他問題。

在我開始發現“代碼異味（Code Smell）”之前，一開始.dropdown-item代碼有十行，我非常喜歡用mixin，mixin是一個能極大減少代碼行數的好東西，它能讓我們快速的知道代碼的大致用途。

雖然使用函數重構代碼并不是都這樣有效，但盡量多用。

好：注解難懂的補丁性的代碼

我對注釋也不是總那么苛刻的，比如我就很難找到下面的注釋的問題，若你曾看過normalize.css的源碼，你一定會注意到它滿滿的注釋，不得不說，真是“極好的”注釋。

欣賞一番：

/** * 1\. Add the correct box sizing in Firefox. * FF下正常的盒子模型 * 2\. Show the overflow in Edge and IE. * 在Edge和IE下overflow為visble */hr { box-sizing: content-box; /* 1 */ height: 0; /* 1 */ overflow: visible; /* 2 */}

若沒有這些注釋，你永遠不知道為何這樣寫。修復特定瀏覽器bug的代碼往往是晦澀難懂的，常常會被當做無用代碼刪掉。

由于Normalize庫的目標是提供一個完全一致樣式環境，所以需要很多這樣的注釋。選擇器都是類型和屬性選擇器，沒有任何class名，同時由于不是可命名的class名，所以自文檔非常困難。

如下為另一段Bootstrap的注釋：

/* Chrome (OSX) fix for https://github.com/twbs/bootstrap/issues/11245 */select { background: #fff !important;}

一個Github鏈接，非常有用。即使不打開連接也能知道這兒是一個bug，而且有可能是一個非常難定位的bug。若有需要，可以通過鏈接獲取更多信息。最棒的是，因為沒有大段大段的文本去解釋bug，所以它并不會打亂代碼邏輯，同時也告訴我們哪里可以獲取更多信息。若使用項目與事務跟蹤工具如JIRA，那么可以直接在注釋中與編號關聯起來。

當然，不是每個打補丁的代碼都要這樣注釋，但若bug不是那么容易發現，而且與瀏覽器怪癖有關，那么還是這樣注釋吧。

好：指令式注釋

一些工具如KSS , 會在CSS文件中創建一些樣式規范。如下：

/*
Alerts
An alert box requires a contextual class to specify its importance.
一個警告信息框需要與語境有關的的類來指定其重要性
Markup:
<div>
 Take note of this important alert message.
</div>
alert-success - Something good or successful 好的或成功的
alert-info - Something worth noting, but not super important 不那么重要的
alert-warning - Something to note, may require attention 需要被提示并記錄，需要引起注意的
alert-danger - Something important. Usually signifies an error. 非常重要的，常用于錯誤
Styleguide Alerts
*/

這不僅僅是注釋，這是規范，它能被KSS解析并用于生成HTML。這已經算是項目文檔的一部分了，而且不得不說，這比手動創建一個分離的HTML文件要好很多，因為其在同一個文件內且始終與代碼相匹配。

另外一種指令式注釋為許可信息，當使用第三方庫并在注釋中注明許可信息時，一般都需要包含。

而我貼出Robert Martin關于注釋的話時，似乎應該解釋一下，但我沒有那么做。因為我認為這是一句容易理解的話，若你還在代碼中到處寫注釋，那么請先思考是否合理。

英文：Keith J. Grant 譯文：眾成翻譯/KING

zcfy.cc/article/thoughts-on-self-documenting-css

本文摘自互聯網，如有侵權，請與小編聯系進行刪除