css帮助文档文档下载_完善CSS文档的8个最佳实践-优快云博客

本文探讨了CSS文档的重要性和最佳实践，包括设置基本规则、解释代码库结构、建立编码标准、避免长样式表、记录CSS与样式指南、将样式表细分为部分、索引样式表内容及找到记录的最佳去处。

css帮助文档文档下载

在CSS领域中，文档使用率较低。由于最终用户看不到文档，因此客户常常忽略其价值。另外，如果这是您的第一次记录代码，则可能很难确定要记录什么以及如何最有效地进行记录。

但是，记录CSS可以为您的项目提供很多帮助：从鼓励更好的代码实践到简化新团队成员的入职。在本文中，我将解释记录CSS的优点，并分享我和Bitovi团队所认为的使文档为您服务的最佳实践，而不是相反。让我们深入研究它。

1.设置基本规则

当您和您的团队不清楚要记录什么或您希望它如何工作时，很难赶上文档浪潮。因此，第一步是就将使用的约定以及如何实现这些约定达成一致。您可以在实时文档中执行此操作，以便团队中的每个人都可以做出贡献。这样，随着您的方法改变或变得更加全面，您可以使其保持最新状态。共享Google文档，代码存储库上的Wiki页面或“生活风格指南”上的页面（甚至更好）都是实现此目的的好地方。

现在让我们看一下您可以包括的实际“基本规则”。

2.解释代码库的结构

了解代码的组织方式后，任何人都可以从第一天开始立即采取行动。一种简单的方法是创建文件结构的映射，您可以在其中解释其中的内容以及应该存放的内容。进行此操作时，请特别注意可能存在歧义的地方。例如，指示文件“ buttons.css”包含按钮样式不是很有帮助，但是指示“ custom”目录是主题的自定义样式所在的位置可以节省时间。

这是一个例子：

Project Root
└── srs
    ├── styles               // Base styles. Styles placed here should be available anywhere in the application     
        ├── bootstrap-custom // Custom styles that overwrite bootstrap
        ├── custom           // Custom styles created for the application
        ├── demos            // Demos to illustrate styles and interactions for the style guide
        ├── fonts           
        ├── img              // Images used ONLY in stylesheets
        ├── variables        // Variables used in the custom theme
        └── styles.less      // Imports of all the base stylesheets
    
    └── components
        ├── alerts       
            └── alert.less   // Custom styles for the alert component. Every component has its own stylesheet that allows to customize it specifically preventing bloat and style leaking.

根据经验，记录需要澄清的地方。并非每个目录和文件都需要文档（例如在上面的示例中，“字体”是不言自明的）。将自己置于该项目的新手的鞋子（或记住那个人的那个时代），并提供希望得到的指导。这样做的方式对您来说并不费时，但对避免重复的问题很有帮助。

这里要指出的另一个关键元素是应在何处添加新样式以及应遵循的所有步骤。上面的示例演示了这一点，但是鉴于CSS的继承特性，值得详细说明它。

例如，在我们使用Bootstrap作为基础框架的项目中，通常会在三个地方放置新规则，这取决于开发人员要实现的目标。因此，我们向包含三种情况的文档添加了指南：

场景1

如果要覆盖Bootstrap定义的样式，则：

找出规则定义在引导框架的哪个样式表中。
转到“ src / styles / bootstrap-custom”。
寻找相同的样式表。
如果不存在，请在该目录中使用相同的名称创建一个新目录。
添加您的覆盖并指出任何重要的内容。
最后，将新样式表导入“ src / styles / style.less”。

场景2

如果要添加不会覆盖Bootstrap的新样式定义，并且该样式定义应在应用程序中的任何位置可用，则：

转到“ src /样式/自定义”。
找到可以添加新样式的样式表（想想：这是用于定义按钮的样式，还是像mixin这样的可重用样式？）并将其放置在最有意义的位置。
如果没有样式表可以放置这种新样式，则创建一个新样式。
按照我们的命名约定命名。
添加您的新样式，并指出任何重要的内容。
最后，将新样式表导入“ src / styles / style.less”。

场景3

如果要为组件添加新的样式定义（这意味着该组件仅在应用程序中使用该组件的位置才可用于该组件），则：

转到“ src / components”。
查找要设置样式的组件。
在组件目录内找到该组件的样式表。
最后，添加新样式并指出任何重要的内容。

本指南：

用于保持我们的样式井井有条。
因为改写是在正确的地方进行的，所以样式要根据我们已经建立的继承来工作。
避免开发人员编写过于复杂的规则。
防止样式泄漏到非预期的元素。

3.建立您的编码标准

您的编码标准或CSS样式指南是指您的团队同意编写CSS的方式。这包括编写代码的最佳实践，例如格式，命名和语法约定。许多公司已经分享了它们的实现方式（来自CSS-Tricks的这篇文章进行了很好的编译： CSS样式指南）。我发现分享此类信息有用的几种方法：

不要做清单

使用此格式可以指出要避免的事情，同时提供可行的替代方法。这消除了歧义，并鼓励人们去做一件特定的事情。例如：

不要	要做
不要使用制表符进行缩进。	请使用四（4）个空格进行缩进。
不要使用under_scores或“ camelCase”来命名类或ID。	请勿使用破折号来分隔单词。
不要使用类和ID名称来反映基础标记结构。 `.container-span`和`.small-header-div`是不好的名字。	一定要从对象的角度考虑CSS，并使用简单的名词作为名称。 `.global-alert`和`.badge`是好名字。
不要使用ID和过于具体的选择器来设置样式。仅在绝对必要时使用它们（例如，表单控件或页面锚）。	请使用类来促进可重用性并减少CSS选择器特异性冲突。

最佳做法清单

将您的指南总结为最佳做法，并提供示例。这将使每个人都易于阅读和理解。例如：

最佳实践	例
在单独的行上编写多个选择器。	.btn， .btn-link { }
在选择器和撑杆之间留出一个空间。	.selector { }
尽可能使用十六进制值的简写形式。	`#fff` vs `#ffffff`
用小写形式写十六进制值。	`#3d3d3d`与`#3D3D3D`
URL用单引号引起来。通常，单引号比双引号更可取，因为它们更容易键入。	`url ('/image.png')`与`url` `("/image.png")`
除角度（deg）和时间（s或ms）外，请勿使用零（0）值的单位。	`margin-right: 0;` vs `margin-right: 0px;`

一个开发人员编写代码的方式可能与另一个开发人员截然不同。这就是为什么您的团队设置编码标准很重要的原因。这样可确保代码在整个项目中保持一致，从而使阅读，编写和查看变得更加容易。但是，请确保您的编码标准中包含的所有内容都是您的团队已同意的惯例。

我参与了一个项目，将其纳入我们的生活方式指南。作为代码的一部分，我们致力于将这些最佳实践并将其推向仓库。然后，为了确保每个人都参与其中，团队中的每个人都必须批准拉取请求，然后我们才能将其合并。这保证了每个人都必须花时间来审查和讨论它。

4.避免使用长样式表

当您将样式分解为更小，更集中的样式表时，记录它们变得更加容易。您也可以省去时间，而不必记录变得不言自明的内容。

例如，您可以为每个变量类型创建一个文件，而不是使用一个800行样式表来包含可以在主题中使用的所有变量。通过不必在文件中上下滚动来查找内容，可以节省时间！最好考虑一下可以节省的时间，因为不必每次添加或重命名新节时都更新索引。

在长文件中，长索引...

/*-------------------------------------------*\
   variables.less

   Index
   - Color Palette
   - Typography
   - Buttons
   - Forms
   - Layout
   - Messaging & Status
   - General
   - Navigation
   - Carousel
   - Jumbotron
\*-------------------------------------------*/

中断文件，不需要索引：

在大型应用程序中工作时要考虑的另一个示例是modlet工作流。它解释了为什么使用按组件组织的较小文件可以更轻松地测试和组装它们。

5.记录CSS并附带样式指南

正确记录CSS的很大一部分与编写好CSS有关，反之亦然。这意味着，即使CSS代码库的状态可能不是最佳状态，执行文档规则也可以使您迈向更好的系统。

在这里记录CSS时要考虑样式指南。其背后的想法是样式指南可以帮助您确定CSS的良好结构，因为要创建CSS，您需要区分以下两个方面：

定义应用程序外观的基线样式（包括您使用的任何CSS框架）
对特定组件进行的自定义，以及
对特定页面进行的自定义。

CSS的大部分应该由基线样式组成，因为它们可以在应用程序中的任何位置使用，并会影响处于默认状态的所有元素。自定义样式应在添加具有特定外观和行为的组件时发生，或者在页面中元素或组件的布局需要它时使用。

捕获此特定设置如何在您的应用程序中工作的好方法是创建样式指南站点地图。一旦知道了样式指南在您的应用程序中的外观，便可以牢记这一点来记录元素。例如，如果您在样式指南中定义了按钮和导航的外观，那么应该为它们添加新的样式和文档（在“ buttons.css”和“ navs.css”中）很明显。但是，由按钮组成的导航又如何呢？

拥有样式指南可以帮助您做出决定，因为您可以从显示和标记的角度比较按钮和导航的外观。让我们来看这个例子：

<button type="button" class="btn btn-primary">Primary</button>
<button type="button" class="btn btn-secondary">Secondary</button>
<button type="button" class="btn btn-emphasis">Emphasis</button>

<button type="button" class="btn btn-primary disabled">Primary</button>
<button type="button" class="btn btn-secondary disabled">Secondary</button>
<button type="button" class="btn btn-emphasis disabled">Emphasis</button>

<ul class="nav nav-tabs">
     <li class="active"><a href="#">Active</a></li>
     <li><a href="#">Nav Item</a></li>
     <li><a href="#">Nav Item</a></li>
     <li class="disabled"><a href="#">Nav Item</a></li>
</ul>

在这种情况下，CSS有两个可能的位置，这些位置将定义由按钮组成的导航：

如果标记遵循其他导航的结构，则使用链接列表或带有链接的<nav>看起来像按钮，然后将导航样式添加到“ navs.css”。
如果要使用的标记是<button> ，则将样式添加到“ buttons.css”。您甚至可以将其添加为单独的样式表（例如“ buttons-group.css”）。在这种情况下，“导航”一词将不再适用，因为HTML按钮作为导航项的访问性较小。

6.将样式表细分为部分

将样式表分解为更易于管理的文件后，您可以通过将每种样式分解为单独的部分来继续此练习。

首先，每个样式表至少应包含一个标题和（如果有用）简短描述。标题可以和文件名一样简单，大写看起来更像标题（例如：样式表“ buttons.css”的“ Buttons”），也可以与文件名相同，例如这个：

/**
 * icons.css
 */

.icon {
  font-family: 'bitovi';
  speak: none;
  font-style: normal;
  font-weight: normal;
  font-variant: normal;
  text-transform: none;
  line-height: 1;
}

我发现在浏览器中调试代码时，尤其是在文件已与其他文件一起编译时，使用文件名特别有用，因为我可以获得对样式所在的文件的引用。

另外，请注意，我使用的注释样式以/**开头 vs只是/* 。这是JSDoc中使用的约定，用于解析应包含在自动生成的文档中的注释。我建议使用这种样式，因为许多生活风格指南生成器都使用JSDoc格式，因此当您准备使用生成器时，您的代码将需要很少的额外工作。

无论如何，您都可以使用其他样式来表示一个部分，例如：

/*-------------------------------------------*\
    icons.css
\*-------------------------------------------*/

.icon {
  font-family: 'bitovi';
  speak: none;
  font-style: normal;
  font-weight: normal;
  font-variant: normal;
  text-transform: none;
  line-height: 1;
}

在某种程度上，这取决于您的团队是否认为是使某个部分脱颖而出的最佳方法。唯一的要求是在开头使用/* ，在结尾使用*/ 。真正重要的是，无论您使用哪种方法，都要坚持使用它，并以一致的方式在CSS代码中使用它。

如果您认为描述在特定样式表中可能有用，则将其添加为该第一条注释的一部分。例如：

/**
 * icons.css
 *
 * Icons should convey in a simple and meaningful way the concept of the function
 * they represent. When designing new icons be sure to remove any complexities 
 * and follow the linear and lightweight appearance of the icon set.
 */

.icon {
  font-family: 'bitovi';
  speak: none;
  font-style: normal;
  font-weight: normal;
  font-variant: normal;
  text-transform: none;
  line-height: 1;
}

这样做将加强将其作为一个部分的想法。另外，尝试将描述分成多行（Harry Roberts建议最多80个字符），以便在打开多个文件或在Github上阅读时更容易阅读。

添加标题和描述后，您可以将样式表中的样式分为几部分，从而更进一步。为此，考虑在逻辑上解释样式表内容的合理性。例如，样式表“ buttons.css”通常会有一个部分，其中仅通过应用类.btn定义按钮的默认样式。然后将有定义不同颜色，大小和配置的其他样式，可以结合使用这些样式以进一步自定义其外观和行为。为每种样式创建节将使您更容易理解和查找应该在哪里出现新的类或覆盖。同样，当代码以摘要形式显示时，查看文件也不会太吓人，而对于长文件则很难分辨样式的开始和结束位置。

让我们看一下这个比较示例。首先，一个没有节的LESS代码块：

.label-condensed-variant(@color) {
  &:before {
    background-color: @color;
  }
}

.label {
  border-radius: 0;
  font-family: @font-family-bold;
  font-size: 85%;
  position: relative;
  &.label--condensed {
    font-size: @font-size-xsmall;
    color: @gray;
    background: transparent;
    padding-right: @padding-small;
    &.label--primary {
      .label-condensed-variant(@label-primary-bg);
    }
    &.label--success {
      .label-condensed-variant(@label-success-bg);
    }
    &.label--info {
      .label-condensed-variant(@label-info-bg);
    }
    &.label-warning {
      .label--condensed-variant(@label-warning-bg);
    }
    &.label--danger {
      .label-condensed-variant(@label-danger-bg);
    }    
  }
  &.label--simple {
    font-family: @font-family-base;
    font-size: @font-size-xsmall - 1;
    color: @gray;
    border: 1px solid @gray-light;
    padding: 2px;
    border-radius: @border-radius-small;
    text-transform: uppercase;
  }
}

和带有部分的相同代码块：

/**
 * bootstrap-custom/_labels.less Labels
 * 
 * Overwrites the default styles defined by the bootstrap framework.
 *
 */

.label {
  border-radius: 0;
  font-family: @font-family-bold;
  font-size: 85%;
  position: relative;
}


/**
 * Condensed Labels
 *
 * Modifies labels to provide a smaller and narrower version with a colored circle to be used in areas with little space (for example in list views).
 */

.label {
  &.label--condensed {
    font-size: @font-size-xsmall;
    color: @gray;
    background: transparent;
    padding-right: @padding-small;    
  }
}


/**
 * Condensed Labels - Colors
 */

.label-condensed-variant(@color) { // Variant mixin to set the circle color
  &:before {
    background-color: @color;
  }
}

.label {
  &.label--condensed {
    &.label--primary {
      .label-condensed-variant(@label-primary-bg);
    }
    &.label--success {
      .label-condensed-variant(@label-success-bg);
    }
    &.label--info {
      .label-condensed-variant(@label-info-bg);
    }
    &.label--warning {
      .label-condensed-variant(@label-warning-bg);
    }
    &.label--danger {
      .label-condensed-variant(@label-danger-bg);
    }
  }
}


/**
 * Simple Labels
 *
 * Modifies labels to provide a simple linear version where colors are not used.
 */

.label {
  &.label--simple {
    font-family: @font-family-base;
    font-size: @font-size-xsmall - 1;
    color: @gray;
    border: 1px solid @gray-light;
    padding: @padding-small;
    border-radius: @border-radius-small;
    text-transform: uppercase;
  }
}

7.索引样式表的内容

这是提供样式表内容快照的绝妙方法，而无论出于何种原因，这些项目都必须保留长的样式表（不是那些项目的拥护者，但确实会发生！），这是一个很棒的方法。

样式表索引通常如下所示：

/**
 * icons.css
 *
 * Icons should convey in a simple and meaningful way the concept of the function
 * they represent. When designing new icons be sure to remove any complexities 
 * and follow the linear and lightweight appearance of the icon set.
 *
 * Index
 * - Icon Font
 * - Icon Variations
 * - Icon Animations
 *
 */

尽管我喜欢它们的实用性和实用性，但我不得不承认它们很容易被遗忘，因此已经过时了。当它们很长并且您使用数字时，它们也很难更新（因此请避免使用它们！）

使用索引的另一种方法是让样式指南生成器通过查看样式表，查找已定义的部分并为您生成索引来为您完成工作。我将在本文结尾处进一步扩展该主题。

8.找到记录的最佳去处

这就是记录的秘密所在。很容易迷失方向，一次陷入文档狂潮，然后忘掉它，最后只有一部分代码库被过度记录，而其余部分则未被记录。与生活中的一切一样，秘诀是找到平衡。记录那些需要注意的区域，因为有不可预见的依赖项 ， 其他资源或重要注意事项 。就是说，并非应该记录每一个代码段，但是将其分成多个块并在必要时解释这些块是绝对有用的。通过这种方式，文档成为工作流程中有用的工具，而不是您避免做的事后思考。但是，您究竟该怎么做呢？这是一个例子：

假设您要为以下卡片组件实现标记和CSS：

查看设计，您可以确定以下样式模式：

卡座设计
卡片网格
卡清单
卡暗版

然后，您可以牢记这些模式来分解CSS实施，并使用文档进行指导。首先，“ cards.css”样式表可以包含一个简单的介绍，如下所示：

/**
 * cards.css
 *
 * These are the styles for the card component.
 *
 * Index
 * - Card Base 
 * - Card Grid
 * - Card List
 * - Card Dark
 */

您可以在简介中包含更多有用的信息，但是由于您刚刚入门，因此简单的操作可以帮助奠定文档框架。

然后，让我们添加将在其中使用样式的部分：

/**
 * cards.css
 *
 * These are the styles for the card component.
 *
 * Index
 * - Card Base 
 * - Card Grid
 * - Card List
 * - Card Dark
 */


/**
 * Card Base
 */


/**
 * Card Grid
 */


/**
 * Card List
 */


/**
 * Card Dark
 */

考虑到这些部分，您可以可视化代码的结构。您知道应该使卡的基本定义足够灵活和独立，以便可以轻松使卡以网格，列表或深色版本工作。

然后，在编写代码时，您的注释将变得更加具体：

/**
 * Card Base
 *
 * Defines the appearance and behaviour of the default card with its main parts:
 * - Card Image
 * - Card Content
 * - Card Footer
*/

.card {...}
.card__image {...}
.card__logo {...}
.card__content {...}
.card__footer {...}

我认为这是您应该包括的基本文档级别，因为它可作为布局代码的指南，并Swift告知下一个工作人员如何组织事物。

下一级别是添加特定于规则的注释，这些注释可用于解释该规则的作用，因为乍一看它并不明显。例如：

/**
 * Card Base
 *
 * Defines the appearance and behaviour of the default card with its multiple parts:
 * - Card Image
 * - Card Logo
 * - Card Content
 * - Card Footer
*/

.card {
  @media (max-width: {{ screen-xs }} ) {
    border: none;   /* because the card takes 100% of the screen on mobile */
  }
}
.card__image {...}
.card__logo {...}
.card__content {
  flex: 1 1 auto;   /* "auto" needs to be explicit to avoid the div collapsing on IE.*/
}

这种方法的优点在于，文档可以随时随地支持和通知实现，而以后会添加一些内容。

这是Bootstrap框架的另外两个示例，它们显示了何时注释有用以及何时值得更详细地说明。

例子1

// Need .dropdown-toggle since :last-child doesn't apply, 
// given that a .dropdown-menu is used immediately after it

.btn-group > .btn:last-child:not(:first-child),
.btn-group > .dropdown-toggle:not(:first-child) {
 .border-left-radius(0);
}

此注释阐明了为什么存在这些样式以及它们在做什么。它也很简短，而且很关键，可以用随意的语言传达想法。

范例＃2

// Checkbox and radio options
//
// In order to support the browser's form validation feedback, powered by the
// `required` attribute, we have to "hide" the inputs via `clip`. We cannot use
// `display: none;` or `visibility: hidden;` as that also hides the popover.
// Simply visually hiding the inputs via `opacity` would leave them clickable in
// certain cases which is prevented by using `clip` and `pointer-events`.
// This way, we ensure a DOM element is visible to position the popover from.
//
// See https://github.com/twbs/bootstrap/pull/12794 and
// https://github.com/twbs/bootstrap/pull/14559 for more information.

[data-toggle="buttons"] {
 > .btn,
 > .btn-group > .btn {
   input[type="radio"],
   input[type="checkbox"] {
     position: absolute;
     clip: rect(0,0,0,0);
     pointer-events: none;
   }
 }
}

这是一个很好的文档示例，它进行了更深入的介绍，解释了实现决策背后的逻辑并提供了指向其他信息的链接。

更进一步

考虑到这些最佳实践，下一步就是将一种生活风格指南纳入您的文档中。生活风格指南是一个生活文档，它显示了您包含在代码中（如网站）的注释，因此您可以与源代码分开浏览该文档。

使生活风格指南功能强大的原因在于，实际文档与代码一起存在，并且可以随代码更改而轻松更新，从而使其保持同步和相关。另一个好处是，您可以使该文档可供团队中其他可能不直接与代码进行交互的人员（例如设计师，产品经理或QA工程师）使用。这些团队成员也会发现了解用户界面的形成方式很有帮助。

在生活风格指南中，您可以包括代码的交互式演示，并且可以独立于代码结构进一步组织文档。

结论

记录CSS始于清晰的规则和结构良好的代码库。当作为工作流的一部分完成时，它还可以作为结构代码并随着代码的增长而组织起来的指南。这还有一个额外的好处，那就是弄清楚事物在哪里以及应该在哪里添加新代码，从而在快速跟踪开发过程中简化了新成员的入职工作。

翻译自: https://webdesign.tutsplus.com/articles/css-documentation-best-practices--cms-30139