上一期我们讲到了 完美CSS文档的8个最佳实践3 里面的第五条和第六条,
第一条和第二条在这里可以看到 完美CSS文档的8个最佳实践1
第三条和第四条在这里可以看到 完美CSS文档的8个最佳实践2
现在这篇文章就主要讲第五条和第六条,下面进入正文
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 {...}
我认为这是您应该包括的基本文档级别,因为它可以作为布局代码的指导,并快速通知下一个工作人员的组织情况。
下一个级别是添加特定于规则的注释,并且可以用来解释这个规则在做什么,因为它一目了然并不明显。例如:
/**
* 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, <font></font>
// given that a .dropdown-menu is used immediately after it<font></font>
<font></font>
.btn-group > .btn:last-child:not(:first-child),<font></font>
.btn-group > .dropdown-toggle:not(:first-child) {<font></font>
.border-left-radius(0);<font></font>
}
这个评论澄清了为什么这些风格存在,他们在做什么。这也是简短的,以一种随便的语言传达这个想法。
例#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工程师)。这些团队成员也会发现知道UI是如何形成的。
在一个生活方式指南,你可以包括代码的交互式演示,你可以进一步独立于代码结构组织你的文档。
结论
记录CSS从清晰的规则和结构良好的代码库开始。作为工作流程的一部分完成后,它也可以作为构建代码的指导,并随着其发展而保持组织。这还有一个好处,就是明确事情发生的地点,以及在哪里添加新的代码,在快速跟踪开发的同时简化新成员的加入。
相关文章链接:
第一条和第二条在这里可以看到 完美CSS文档的8个最佳实践1
第三条和第四条在这里可以看到 完美CSS文档的8个最佳实践2
第五条和第六条在这里可以看到 完美CSS文档的8个最佳实践3
第七条和第八条在这里可以看到 完美CSS文档的8个最佳实践4