关于CSS自文档的思考_css声明式语言式代码注释

原文出处 Thoughts on Self-Documenting CSS

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

if (employee.isEligibleForFullBenefits()) {
  …
}

那么对CSS而言呢？

// Addresses
address {…}

// Unordered and Ordered lists
ul,
ol {…}

// Blockquotes
blockquote {…}

不好： 块分隔注释

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

不好：解释语法

// Allow breaking very long words so they don't overflow the tooltip's bounds
// 设置长单词换行
word-wrap: break-word;

不好：对库进行介绍

// 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;

不好: 过时的注释

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

有时有用的：有特殊意义的注释

.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
}

.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;
}

.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;
}

好：注解难懂的补丁性的代码

/**
 * 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 */
}

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

好：指令式注释

/*
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
*/