可編程CSS代碼說明文檔的幾種選擇

01-31

本文為譯文，原文請閱讀The Options for Programmatically Documenting CSS

我堅信代碼說明文檔應當儘可能維護在緊靠源碼的位置。就我個人經歷而言，這是令代碼說明文檔長期有效的唯一選擇。那些維護在源碼外部的文檔、筆記、知識集最終都逃脫不了過期、被遺忘或者被遺失的命運。 n

代碼說明文檔總是一個令我心煩的話題。嚴重缺失代碼說明文檔的代碼庫對於其使用者來說，如同一個定時炸彈。這很容易讓剛接手項目的工作者對工作產生厭惡情緒。從另一方面來考慮，不良的代碼說明文檔會催生低卡車因子（low truck factor)，可以理解為：一個團隊最多失去幾位成員才會導致項目陷入困境）。 n

最近我剛接手了一個不止1500頁word代碼說明文檔的項目。這些代碼說明文檔不是過時，就是缺乏組織性。除了確定這是個災難，我也必須堅信一定會有更好的辦法！ n

不久前，我在CSS-Tricks上發表了文章What Does a Well-Documented CSS Codebase Look Like?，跟大家簡單探討了一些關於代碼說明文檔的問題。這次，讓我們進一步探究用編程方式編寫代碼說明文檔的幾種方式，特別是對CSS編寫代碼說明文檔。n

與JSDoc類似，CSS代碼也有多種描述組件的方式，例如在源碼種加註釋 /* comments */。一旦代碼加上了這樣的注釋，那麼一份活著的樣式指南便生成了。之所以強調活著，因為它是代碼說明文檔可維護性的關鍵成功因素。根據我的經驗，採用這種方式很快就能體會到如下幾點益處：

整個團隊使用共同的辭彙，大大減少溝通問題和誤解。
組件視覺效果的當前狀態始終可見。
用最小的代價把前端代碼庫轉變成精心描述的樣品庫。
它是個有用的開發試驗田。

有時候這種聚焦於文檔的開發方式也會被詬病為是相當耗費時間的。對此，我不作反駁。每個人都應當在代碼功能與說明文檔之間爭取平衡。拿我現在的團隊舉例，我們採用敏捷的開發方式，每個迭代都會預留部分時間專門用於補全缺失的文檔。

當然，很多時候人們會認同可運行的軟體勝於詳盡的文檔。這也完全正確，只要負責人清楚項目的長期維護計劃即可。

Knyle Style Sheets (KSS)

KSS既是一份文檔規格說明，也是一種編寫樣式指南的格式。它為團隊編寫具有可維護性、可文檔化的CSS提供一套方法。我周圍的大多數同行們採用KSS，是因為它具有較高的人氣、豐富的表現力以及簡潔的特點。

KSS的編寫格具有可讀、可解析的特點。因此，它旨在幫助人們自動化地創建活著的樣式指南。

類似於JSDoc，KSS允許在CSS的源代碼中添加註釋來描述組件。每一段KSS文檔塊由三部分組成：描述元素的功能、外觀；羅列一下修飾類、偽類如何修改元素；指出樣式指南中元素所在的位置。SCSS的代碼舉例如下：

// Primary Buttonn//n// Use this class for the primary call to action button.n// Typically youll want to use either a `<button>` or an `<a>` element.n//n// Markup:n// <button class="btn btn--primary">Click Me</button>n// <a href="#" class="btn btn--primary">Click Me</a>n//n// Styleguide Components.Buttons.Primaryn.btn--primary {n padding: 10px 20px;n text-transform: uppercase;n font-weight: bold;n bacgkround-color: yellow;n}n

至於用Node.js實現KSS，Benjamin Robertson發表過一篇詳細描述使用kss-node經歷的文章。此外，還有大把的生成器使用KSS標記法將樣式表生成為樣式指南。其中，SC5 Style Generator 是一個很流行的工具。此外，這些生成器的語法得到了擴展，引入了標籤容器、處理時可以忽略樣式表中的部分內容以及其他一些優秀的改進。

另一些時而有用的好處（但在我看來比較花哨的）如下：

使用設計師工具可以之間通過web界面編輯Sass、Less、PostCSS的變數。
針對每一種設備都有樣式的在線預覽。

誰知道呢，可能這些功能在某些用戶場景下是有益的。這裡有個SC5的可交互demo。

GitHub 的樣式指南 (Primer) 就是用KSS生成的。

與JavaScript生態圈不同的是，JsDoc有著王者般地位，但在CSS項目中還有很多不使用KSS規範的代碼說明文檔。因此，再介紹兩個我所了解的CSS代碼說明文檔工具，排列順序按照流行程度、最近的更新以及我的主觀意見。

MDCSS

如果你正在搜索一個簡單、精鍊的解決方案，mdcss 是一個選擇。這裡有一個可交互demo。要叫上一段文檔，加上以`---`開頭的CSS注釋即可。CSS代碼如下：

/*---ntitle: Primary Buttonnsection: Buttonsn---nnUse this class for the primary call to action button.nTypically youll want to use either a `<button>` or an `<a>` elementnn```example:htmln<button class="btn btn--primary">Click</button>n<a href="#" class="btn btn--primary">Click Me</a>n```n*/n.btn--primary {n text-transform: uppercase;n font-weight: bold;n background-color: yellow;n}n

文檔內容用Markdown解析並轉成HTML，這點很棒！此外，文檔中的某塊內容可以從另一個文件中自動帶入，這對於需要更詳盡解釋的說明文檔很有用。CSS代碼如下：

/*---ntitle: Buttonsnimport: buttons.mdn---*/n

每個文檔對象可包含如title(當前部分的)，unique name, context以及其他屬性。

我所了解的有類似功能的其他工具如下：

Styledown | 可交互的demo
Aigis | 可交互的demo

Nucleus

Nucleus 一種活著的樣式指南生成器，它要求組件符合原子性設計理念。Nucleus從DocBlock標記中讀取信息。

原子設計是編寫模塊化樣式的指導原則，Nucleus將樣式的複雜度級別映射到生物化學的測量級別。這導致了較低的選擇器特異性，允許使用者通過簡單的元素組成複雜的實體。如果你不太熟悉原子設計，初始階段的學習曲線會比較陡峭。Nucleus的實體包括以下這些：

Nuclides: 樣式本身不可直接使用（包括：mixing, settings, variables）。
Atoms: 單類元素或選擇器規則（包括：buttons, links, headlines, inputs...）。
Molecules: 一個或多個嵌套規則，但是任何一個規則都不能超過Atom級別。
Structures: 最複雜的類型，可以由多個molecules或structures構成。
...其他更多。

本文通篇用到的按鈕的代碼例子，在這裡就代表一個Atom——一個樣式表中非常基本的元素（單類元素或選擇器）。為了把它標記成Atom，我們需要用`@atom`標籤來標記，並在後面寫上組件的名稱。CSS代碼如下：

/**n * @atom Buttonn * @section Navigation > Buttonsn * @modifiersn * .btn--primary - Use this class for the primary call to action button.n * @markupn * <button class="btn">Click me</button>n * <button class="btn btn--primary">Click me</button>n * <a href="#" class="btn btn--primary">Click Me</a>n */n.btn--primary {n text-transform: uppercase;n font-weight: bold;n bacgkround-color: yellow;n}n

這裡有個可交互的demo。

總結

對於可編程的CSS代碼說明文檔而言，從工具到通用的語法定義，到目前為止還沒有絕對的贏家。

一方面，KSS似乎在引領著大家，所以我認為把KSS的使用融入到一個長期項目是值得考慮的。我的直覺告訴我KSS會存活很久。另一方面，不同的語法選擇、工具，好像Nucleus、MDCSS看起來也很有前途。我會建議你把它們用到短期項目里。

需要強調一點，本文所列舉的所有工具可能實際使用效果都不錯，並有足夠的可伸縮性。因此挑選最適合於你的團隊的工具進行嘗試即可。

如果讀者們願意在評論中分享使用這些工具的經驗，或者推薦使用其他工具，我將不勝感激。