编程规范

同一个项目，用同一个规范

HTML

  • 元素缩进，用两个空格代替制表符(tab)
  • 尽量使用双引号
  • 每行代码尽量少于80字符
  • 为逻辑块加空行
  • 不能省略可选的结束标签(closing tag)（例如：</li>或</body>）
  • 所有logo都是可以点击的链接
  • 尽量遵循HTML标准和语义，但是不要牺牲实用性
  • 尽量使用最少的标签，保持最小的复杂度
  • 尽量避免使用JS生成的标签，不易查找、编辑，降低性能

html5 doctype

要在HTML页面的第一行加标准模式声明，确保在每个浏览器的表现都一样

<!DOCTYPE html>

语言属性

为 html 根元素指定 lang 属性,有助于语音合成工具确定其所应该采用的发音，有助于翻译工具确定其翻译时所应遵守的规则等等

<html lang="zh-CN">
  <!--...-->
</html>

更多关于lang属性的知识可以从 此规范 中了解。

IE 兼容模式

IE 支持通过特定的<meta>标签来确定回制当前页面所采用的IE版本。除非有强烈的特殊要求，否则最好设置为edge mode,从而通知IE采用其所支持的最新的模式。

<meta http-quuiv="X-UA-Compatible" content="IE=Edge">

阅读这篇 stack overflow 上的文章可以获取更多有用的信息。

字符编码

一定要声明字符编码，可以避免使用字符实体标记，使文档编码一致。（一般使用UTF-8编码）

<meta charset="UTF-8"&gt

引入CSS和JavaScript文件

在HTML5规范中，一般不需要指定type属性，因为值是默认的

HTML5 规范链接

使用 CSS 外部链接

<link rel="stylesheet" href="code-guide.css">

使用 CSS 内部表

<style>
  /*...*/
</style>

使用外部 JavaScript

<scirpt src="code.js"></script>

属性顺序

HTML属性应按照特定的顺序出现，以保证易读性

  1. class
  2. id, name
  3. data-*
  4. src, for, type, value, max, max-length, min, pattern
  5. title, alt, palceholder
  6. role, aria-*
  7. required, readonly, disabled

class 用于标识高度可复用组件，该排首位。id 用于标识具体组件，尽量少用（如：页面的书签），排在第二位。

<a class="..." id="..." data-modal="toggle" href="#">
  Example link
</a>

CSS

  • 单独将选择器放在一行
  • 在每个声明块的左花括号前添加一个空格
  • 声明块的右花括号单独放一行
  • 每条声明语句的冒号后插入一个空格
  • 每条声明单独占一行
  • 所有声明以分号结尾，降低出错可能性
  • 以逗号分隔的属性值，每个逗号后面都应该插入一个空格（例如：box-shadow）
  • 不要在rgb()、rgba()、hsl()、或rect()值的内部的逗号后插入空格。利于从多个属性值（既加括号也加表格）中区分多个颜色值（只加括号，不加表格）
  • 省略值或参数小数点前面的0（例如：用.5代替0.5；-.5px代替-0.5px）
  • 十六进制全部小写，易于区分
  • 简写十六进制，用 #fff代替 #ffffff
  • 为选择器属性添加双引号，例如：input[type="text"]
  • 避免 0 值指定单位，用 margin:0; 代替 margin:0px
/* Bad CSS*/
.select, .secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Good CSS */
.select,
.secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px #fff;
}

声明顺序

相关的属性声明归为一组，并按照一定的顺序排列

  1. 定位
  2. 盒模型
  3. 排版（影响内容）
  4. 视觉（visual 边框背景等内容外的修饰）
  5. 其他（misc）

定位（positioning）可以从正常的文档流中移除元素，还能覆盖盒模型（box model）相关的样式，因此排在首位。盒模型排在第二位，决定了组件的尺寸和位置。

其他属性只影响组件的内部（inside）或者不影响前两组，排在后面

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

不要使用 @import

@import指令较慢，增加了额外的请求次数，会导致不可预料的问题。替代办法有：

  • 使用多个&lt;link&gt;元素
  • 通过Sass或Less类似的CSS预处理器将多个CSS文件编译为一个文件
  • 通过Rails、Jekyll或其他系统中提供过CSS文件合并功能

更多知识请参考 steve souders 的文章

媒体查询（media query）的位置

媒体查询放在相关规则附近。不要单独打包放在一个文件中或者底部。如果分开了，可能会被遗忘。

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

带前缀的属性

使用特定厂商的带有前缀的属性时，通过缩进的方式，让每个属性的值在垂直方向对齐，便于多行编辑。

/* 带前缀的属性 */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

单行规则声明

只包含一条声明的样式，建议将语句放在同一行，便于快速编辑和提高易读性。多条声明的语句，还是分为多行。

/* 每行一个声明 */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

简写形式的属性声明

在需要显示地设置所有值的情况下，应该限制使用简写的属性声明。常见的滥用简写声明如：

  • padding
  • margin
  • font
  • background
  • border
  • border-radius
/* Bad example */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Good example */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

大部分时候，不需要为简写声明指定所有值。如：HTML 的 heading 元素只需要设置上下边距的值，必要的时候只用覆盖这两个值。过渡使用简写声明会导致代码混乱，带来不必要的覆盖引起意外的副作用。

MDN（Mozilla Developer Network）上有关于 shorthand properties 的文章，详细介绍了简写属性声明和行为。

Less和Sass中的嵌套

 避免非必要的嵌套，只有在必须将样式限制在父元素内（就是后代选择器），并且存在多个需要嵌套的元素时才能使用嵌套。

// 不用嵌套
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// 有嵌套
.table > thead > tr {
  > th { … }
  > td { … }
}

注释

确保代码能自描述、注释良好并且易于他人理解。好代码能传达上下午关系和代码目的。不要简单地重申组件或 class 名称。

长注释写完整的句子；一般性注解写简洁的短语。

/* 错误注释 */
/* Modal header */
.modal-header {
  ...
}

/* 正确注释 */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

class命名

  • class名称中只能出现小写字符和破折号（dashe）（不是下划线，也不是驼峰命名法）。破折号用于相关class的命名（类似于命名空间）（例如：.btn 和 .btn-danger）
  • 避免过度简写， .btn 代表 button，但是 .s 不能表达任何意思
  • class 名称应对尽可能短，并且意义明确。
  • 使用有意义的名称，使用有组织的或目的明确的名称，不要使用表现形式的名称。
  • 基于最近的父 class 或基本 class 作为新 class 的前缀
  • 使用 .js-* class 赖标识行为（与样式相对），并且不要将这些 class 包含到 CSS 文件中

在为 Sass 和 Less 变量命名时同样可以参考

/* 错误示范 */
.t { ... }
.red { ... }
.header { ... }

/* 正确示范 */
.tweet { ... }
.important { ... }
.tweet-header { ... }

选择器

  • 对于通用元素使用 class，利于渲染性能的优化
  • 经常出现的组件，避免使用属性选择器（例如：[class^="..."]）。浏览器的性能会受到这些因素影响
  • 选择器尽量短，并且县市组成选择器的元素个数，不要超过3个
  • 只有在必要的时候，才将 class 限制在最近的父元素内（就是后代选择器）（例如：不使用带前缀的 class 时 -- 前缀类似于命名空间）
/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

扩展阅读：

代码组织

  • 以组件为单位组织代码段
  • 制定一致的注释规范
  • 使用一致的空白符代码分隔块，利于扫描较大的文档
  • 使用多个CSS文件，将其按照组件而非页面的形式分拆，因为页面会被重组，而组件只会被移动
/*
 * Component section heading
 */

.element { ... }


/*
 * Component section heading
 *
 * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
 */

.element { ... }

/* Contextual sub-component or modifer */
.element-heading { ... }

编辑器配置

将编辑器按照一定的配置进行设置，避免常见的代码不一致和差异：

  • 用两个空格代替制表符（tab）
  • 保存文件时，删除尾部的空白符
  • 文件编码设置为UTF-8
  • 在文件结尾添加一个空行

参照文档并将这些配置信息添加到项目的 .editorconfig 文件中。例如：Bootstrap 中的 .editorconfig 实例。更多信息请参考 about EditorConfig。

 

本文转自：http://codeguide.bootcss.com/#html-syntax

posted @ 2019-08-07 10:22  任大嘴就是我  阅读(174)  评论(0)    收藏  举报