以编程方式记录 CSS 的选项

我坚信文档应该尽可能地靠近代码。根据我的经验，这是长期有效唯一的选择。外部文档、笔记和维基最终都会过时、被遗忘和丢失。

文档一直是我头疼的问题。处理文档编写不佳的代码库就像一颗定时炸弹。它使入职过程变得乏味。另一种看待不良文档的方式是，它有助于培养 低卡车系数（即，“团队中必须被卡车撞倒多少人才会使项目陷入严重困境”）。

最近，我加入了一个项目，该项目拥有超过 1500 页的文档，这些文档是用……Microsoft Word 编写的。它已经过时且杂乱无章。一场真正的灾难。一定有更好的方法！

我之前也讨论过这个文档问题。不久前，我在 CSS-Tricks 上的文章 良好记录的 CSS 代码库是什么样的？ 中简单地提到了它。现在，让我们深入探讨以编程方式记录代码的选项。特别是 CSS。

类似于 JSDoc，在 CSS 世界中，可以通过 /* comments */ 在源代码中描述组件。一旦代码通过这种方式用注释进行描述，就可以生成项目的**动态样式指南**。我希望我已经足够强调**动态**这个词，因为我相信这是成功维护的关键。根据我的经验，通过这种方式记录代码可以立即获得许多好处

• 团队开始使用通用词汇，显著减少了沟通问题和误解。
• 组件的当前视觉 UI 状态始终存在。
• 有助于将前端代码库转换为描述良好的模式库，且工作量最小。
• 作为开发游乐场很有用。

有时有人认为以文档为中心的开发方法非常耗时。我不会否认这一点。人们应该始终在构建功能和编写文档之间寻求平衡。例如，在我当前所在的团队中，我们使用敏捷方法来构建内容，并且每个冲刺中都有一段时间专门用于完成缺少的文档。

当然，有时工作的软件优于全面的文档。这完全没问题，只要相关人员**意识到并制定了项目如何长期维护的计划**。

现在让我们看一下 CSS 中最流行的文档选项

Knyle 样式表 (KSS)

KSS 是一种文档规范和样式指南格式。它试图提供一种方法，以便团队在编写可维护的、有文档记录的 CSS。由于其流行、表达力和简单性，我网络中的大多数开发人员都在使用它。

KSS 格式是人类可读的且机器可解析的。因此，它旨在帮助自动创建动态样式指南。

类似于 JSDoc，在 KSS 中，CSS 组件在源代码中以注释的形式进行描述。每个 KSS 文档块包含三个部分：元素的功能或外观描述、修饰符类或伪类的列表以及它们如何修改元素，以及元素在样式指南中的位置参考。以下是其外观

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

Benjamin Robertson 详细描述了他使用 kss-node 的经验，kss-node 是 KSS 的 Node.js 实现。此外，还有许多生成器使用 KSS 符号从样式表生成样式指南。值得一提的一个流行选项是 SC5 样式生成器。此外，它们的文档语法扩展了选项，以引入包装器标记、忽略样式表中某些部分的处理以及其他不错的增强功能。

其他有时有用（但在我看来大多很花哨）的东西是

• 使用设计器工具，您可以通过 Web 界面直接编辑 Sass、Less 或 PostCSS 变量。
• 每个设备上都有样式的实时预览。

谁知道呢，它们可能对某些用例有益。这是一个 SC5 的交互式演示。

与 JavaScript 世界不同，在 JavaScript 世界中 JSDoc 占据主导地位，仍然有很多工具不使用 KSS 约定。因此，让我们探索我了解的两种替代方案，根据流行度、最近的更新和我的主观意见进行排名。

MDCSS

如果您正在寻找简单、简洁的解决方案，mdcss 可能是答案。这是一个交互式演示。要添加一段文档，请编写一个以三个破折号 --- 开头的 CSS 注释，如下所示

/*---
title:   Primary Button
section: Buttons
---

Use this class for the primary call to action button.
Typically you'll want to use either a `<button>` or an `<a>` element

```example:html
<button class="btn btn--primary">Click</button>
<a href="#" class="btn btn--primary">Click Me</a>
```
*/
.btn--primary {
    text-transform: uppercase;
    font-weight: bold;
    background-color: yellow;
}

文档部分的内容由 Markdown 解析并转换为 HTML，这非常不错！此外，文档部分的内容可以自动从另一个文件导入，这对于更详细的解释非常有用

/*---
title:  Buttons
import: buttons.md
---*/

每个文档对象可以包含许多属性，例如标题（当前部分的标题）、唯一名称、上下文以及 其他一些属性。

其他一些我关注的工具，具有非常相似的功能是

• Styledown | 交互式演示
• Aigis | 交互式演示

Nucleus

Nucleus 是一个用于基于 原子设计 组件的动态样式指南生成器。Nucleus 从 DocBlock 注释中读取信息。

原子设计是一种编写模块化样式的指南，在（生物）化学尺度上投射不同级别的复杂性。这导致选择器特异性低，并允许您将复杂实体组合成简单的元素。如果您不太熟悉原子设计，那么在开始时学习曲线可能会让人感到有些不知所措。Nucleus 的实体包括

• 核素：本身不可直接使用的样式（混合、设置、变量）。
• 原子：单类元素或选择器规则（按钮、链接、标题、输入……）。
• 分子：一个或多个嵌套规则，但每个规则不超过一个原子
• 结构：最复杂的类型，可能包含多个分子或其他结构。
• ……以及 更多。

我们在本文中使用的按钮示例代表一个**原子**——样式表中一个非常基本的元素（单类元素或选择器）。为了将其标记为原子，我们需要使用 @atom 标记对其进行注释，后跟组件的名称

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

这是一个 交互式演示。

结论

在以编程方式记录 CSS 的工具或通用语法定义方面，还没有明确的赢家。

一方面，KSS 似乎处于领先地位，因此我认为对于长期项目来说，值得考虑它。我的直觉是它会持续很长时间。另一方面，不同的语法选项和工具（如 Nucleus 和 MDCSS）也看起来很有前景。我建议您在短期项目中尝试它们。

需要注意的是，本文中介绍的所有工具都可能很好地完成工作，并且看起来足够可扩展。因此，请尝试它们并选择最适合您团队的工具。

如果您知道或有使用任何这些工具或其他值得了解的工具的经验，请在下面的评论中分享，我将不胜感激！