注釋

CSS 是一個(gè)棘手的語言，充滿了駭客行為和古怪的事情。因此，應(yīng)該大量注釋，特別是如果有人打算六個(gè)月或一年后要繼續(xù)閱讀和更新這些代碼。不要讓任何人處于如此境地：這不是我寫的，上帝，為什么會(huì)這樣。

CSS 的實(shí)現(xiàn)很簡單，但我們需要為此付出巨大的注釋量。解釋如下：

• 一個(gè)文件的結(jié)構(gòu)或者作用；
• 規(guī)則集的目標(biāo)；
• 使用幻數(shù)背后的目的；
• CSS 聲明的原因；
• CSS 聲明的順序；
• 方法執(zhí)行背后的邏輯思維。

在這里，我可能還遺漏了其他各種各樣的緣由。在代碼完成之時(shí)立即注釋，往往只需花費(fèi)一點(diǎn)時(shí)間；而過一陣時(shí)間再來為一小段代碼注釋，則是完全不現(xiàn)實(shí)和令人惱怒的。

標(biāo)示注釋

理想上，任何 CSS 規(guī)則集之前都應(yīng)該使用 C 風(fēng)格注釋來解釋 CSS 塊的核心。這個(gè)注釋也要記錄對(duì)規(guī)則集特定部分編號(hào)的解釋。比如：

/**
 * Helper class to truncate and add ellipsis to a string too long for it to fit
 * on a single line.
 * 1. Prevent content from wrapping, forcing it on a single line.
 * 2. Add ellipsis at the end of the line.
 */
.ellipsis {
  white-space: nowrap; /* 1 */
  text-overflow: ellipsis; /* 2 */
  overflow: hidden;
}

基本上，任何不能明顯看出意義的地方都應(yīng)該注釋，但不要隨處注釋。記住不要注釋太多，掌握尺度讓每一處注釋都有意義。

當(dāng)注釋 Sass 的一個(gè)特定部分時(shí)，應(yīng)該使用 Sass 單行注釋而不是 C 風(fēng)格的注釋塊。這么做將不會(huì)輸出注釋，即使是在開發(fā)時(shí)的擴(kuò)展模式。

// Add current module to the list of imported modules.
// `!global` flag is required so it actually updates the global variable.
$imported-modules: append($imported-modules, $module) 

在 CSS 編程指南中的注釋一節(jié)中也提到，支持這種方式的注釋。

文檔

每一個(gè)旨在代碼庫中復(fù)用的變量、函數(shù)、混合宏和占位符，都應(yīng)該使用 SassDoc 記錄下來作為全部 API 的一部分。

/// Vertical rhythm baseline used all over the code base.
/// @type Length
$vertical-rhythm-baseline: 1.5rem;

SassDoc 主要有兩個(gè)作用：

• 作為公有或私有 API 的一部分，在所有的地方使用一個(gè)注釋系統(tǒng)強(qiáng)制標(biāo)準(zhǔn)化注釋。
• 通過使用任意的 SassDoc 終端(CLI tool, Grunt, Gulp, Broccoli, Node...)，能夠生成 API 文檔的 HTML 版本。

http://wiki.jikexueyuan.com/project/sass-guidelines/images/2.1.png" alt="" />

本文檔由 SassDoc 生成

這里有一個(gè)深入整合 SassDoc 生成文檔的例子：

/// Mixin helping defining both `width` and `height` simultaneously.
///
/// @author Hugo Giraudel
///
/// @access public
///
/// @param {Length} $width - Element’s `width`
/// @param {Length} $height [$width] - Element’s `height`
///
/// @example scss - Usage
///   .foo {
///     @include size(10em);
///   }
///
///   .bar {
///     @include size(100%, 10em);
///   }
///
/// @example css - CSS output
///   .foo {
///     width: 10em;
///     height: 10em;
///   }
///
///   .bar {
///     width: 100%;
///     height: 10em;
///   }
@mixin size($width, $height: $width) {
  width: $width;
  height: $height;
}