文件名
均采用小写方式, 以中划线分隔, 如有复数结构时, 采用复数命名法
目录名: scripts,styles,images,data-models
文件名: example.JS retina-sprites.CSS
JavaScript
注释
何时使用
难于理解的代码段
可能存在错误的代码段
浏览器特殊的 HACK 代码
想吐槽的产品逻辑, 合作同事
业务逻辑强相关的代码
- // 单行注释斜杠后面要留有一个空格
- /*
- * 多行注释最少三行, 注释内容与星标前保留一个空格
- */
- var hello = ''; // 描述变量可以这样写在变量右边
- /*
- * 描述方法 (函数) 必须使用多行描述
- * 如有必要可以加上参数和返回值说明, 参考 http://usejsdoc.org/
- * @param {Object} balabalabala
- * @return {Object} balabalabala
- */
- function foo() {
- // 描述下面代码时做什么的, 方法第一行不需要留空格
- doSomething();
- // 描述下面代码时做什么的, 上方需要留一个空行
- afterDoSomething();
- if (flag) {
- // 描述下面代码时做什么的, 代码块的第一行也不需要留空格
- drive();
- }
- }
语法
使用四个空格的 soft tabs - 这是保证代码在各种环境下显示一致的唯一方式.
一般情况下 有关键字的地方都要有空格
字符串使用单引号而不是双引号:`var str = 'hello world';`
单行长度, 理论上不要超过 80 列, 不过如果编辑器开启 soft wrap 的话可以不考虑单行长度
接上一条, 如果需要换行, 存在操作符的情况, 一定在操作符后换行, 然后换的行缩进 4 个空格
这里要注意, 如果是多次换行的话就没有必要继续缩进了, 比如说下面这种就是最佳格式.
- if (typeof qqfind === "undefined" ||
- typeof qqfind.cdnrejected === "undefined" ||
- qqfind.cdnrejected !== true) {
- url = "http://pub.idqqimg.com/qqfind/js/location4.js";
- } else {
- url = "http://find.qq.com/js/location4.js";
- }
创建 Object 对象
- // Bad
- var team = new Team();
- team.title = "AlloyTeam";
- team.count = 25;
- // Good
- var team = {
- title: "AlloyTeam", // 冒号后需要跟一个空格
- count: 25
- };
创建 Array 对象
- // Bad
- var colors = new Array("red", "green", "blue");
- var numbers = new Array(1, 2, 3, 4);
- // Good
- var colors = [ "red", "green", "blue" ]; // 中括号左右均需要一个空格
- var numbers = [ 1, 2, 3, 4 ];
构造函数
- /**
- * 创建一个构造函数
- */
- function Modal(options) { // 函数名使用大写字母开头, 驼峰式命名
- this.width = options.width; // 属性在构造函数体中定义
- this.height = options.height;
- }
- Modal.prototype.show = function() { // 方法定义在原型链上
- // show
- }
- Modal.prototype.hide = function() {
- // hide
- }
- // 实例化对象
- var modal = new Modal({
- width: 200,
- height: 300
- });
if 语法
- // if else 前后留有空格,
- if (flag) {
- } else {
- }
for 语法
- // 普通 for
- var values = [ 1, 2, 3, 4, 5, 6, 7 ],
- i, len;
- for (i=0, len=values.length; i<len; i++) {
- process(values[i]);
- }
- // for in, (一般情况下不要用 for in)
- var prop;
- for (prop in object) {
- // 注意这里一定要有 hasOwnProperty 的判断, 不要把原型链上的属性枚举出来
- if (object.hasOwnProperty(prop)) {
- console.log("Property name is" + prop);
- console.log("Property value is" + object[prop]);
- }
- }
switch 语法
- // switch 和括号之间有空格, case 需要缩进, break 之后跟下一个 case 中间留一个空行
- switch (condition) {
- case "first":
- // code
- break;
- case "third":
- // code
- break;
- default:
- // code
- }
- // 没有 default 的情况需要注释特别说明
- switch(condition) {
- case "first":
- // code
- break;
- case "second":
- // code
- break;
- // no default
- }
声明
变量声明
- var _body = $(document.body); // 全局变量使用下划线 _ 开头
- function foo() {
- var result, // 一个代码块里的变量声明只用一个 var
- length, // 一个变量一行, 行末跟注释
- mainWrap;// 驼峰式命名法
- }
常量声明
使用全大写字母 + 下划线的命名方式方式
var IMAGE_DOMAIN = 'WWW.XXX.COM';
函数声明
函数声明统一使用 function 命令进行声明
- // good
- function foo() { // 小括号前不需要空格, 小括号与大括号间需要一个空格
- doSomething(); // 函数调用括号前后不需要空格
- return "hello world";
- }
- // bad
- var foo = function() {
- return "hello world";
- }
- // bad
- var foo = new Function(
- 'return"hello world"'
- );
立即执行函数的写法, 最外层必须包一层括号
- // Good
- (function() {
- "use strict"; // 使用严格模式
- function doSomething() {
- // code
- }
- function doSomethingElse() {
- // code
- }
- })();
空行
说明: 下面代码中的注释处代表着实际代码中的空行
- function foo1() {
- }
- // 方法之间加空行
- function foo2() {
- }
- // 逻辑块与方法之间加空行增加可读性
- for (var i=0; i<10; i++) {
- }
- // 逻辑块之间加空行增加可读性
- if (flag) {
- } else {
- }
- // 文件结尾留一个空行
杂项
只有字符串类型允许使用 == !=, 如 if(x == 'a') 其他情况一律用严格比较条件 === !==
eval 非特殊业务, 禁用!!!
with 非特殊业务, 禁用!!!
CSS
语法
使用组合选择器时, 保持每个独立的选择器占用一行.
为了代码的易读性, 在每个声明的左括号前增加一个空格.
声明块的右括号应该另起一行.
每条声明 : 后应该插入一个空格.
每条声明应该只占用一行来保证错误报告更加准确.
所有声明应该以分号结尾. 虽然最后一条声明后的分号是可选的, 但是如果没有他, 你的代码会更容易出错.
逗号分隔的取值, 都应该在逗号之后增加一个空格. 比如说 box-shadow
不要在颜色值 rgb() rgba() hsl() hsla()和 rect() 中增加空格
不要带有取值前面不必要的 0 (比如, 使用 .5 替代 0.5).
所有的十六进制值都应该使用小写字母, 例如 #fff. 因为小写字母有更多样的外形, 在浏览文档时, 他们能够更轻松的被区分开来.
为选择器中的属性取值添加引号, 例如 input[type="text"]. 他们只在某些情况下可有可无, 所以都使用引号可以增加一致性.
不要为 0 指明单位, 比如使用 margin: 0; 而不是 margin: 0px;.
- /* Bad CSS */
- .selector, .selector-secondary, .selector[type=text] {
- padding: 15px;
- margin: 0px 0px 15px;
- background-color: rgba(0, 0, 0, 0.5);
- box-shadow: 0 1px 2px #C0C0C0, inset 0 1px 0 #F8F8F8
- }
- /* Good CSS */
- .selector,
- .selector-secondary,
- .selector[type="text"] {
- padding: 15px;
- margin-bottom: 15px;
- background-color: rgba(0,0,0,.5);
- box-shadow: 0 1px 2px #c0c0c0, inset 0 1px 0 #f8f8f8;
- }
声明顺序
相关的属性声明应该以下面的顺序分组处理:
Positioning
Box model 盒模型
Typographic 排版
Visual 外观
Positioning 处在第一位, 因为他可以使一个元素脱离正常文本流, 并且覆盖盒模型相关的样式. 盒模型紧跟其后, 因为他决定了一个组件的大小和位置.
其他属性只在组件 内部 起作用或者不会对前面两种情况的结果产生影响, 所以他们排在后面.
关于完整的属性以及他们的顺序, 请参考 Recess https://twitter.github.com/recess
- .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;
- }
Class 命名
保持 Class 命名为全小写, 可以使用短划线(不要使用下划线和 camelCase 命名). 短划线应该作为相关类的自然间断.(例如,.btn 和 .btn-danger).
避免过度使用简写..btn 可以很好地描述 button, 但是 .s 不能代表任何元素.
使用 .JS-* classes 来表示行为(相对于样式), 但是不要在 CSS 中包含这些 classes.
- /* Bad example */
- .t {
- ...
- }
- .red {
- ...
- }
- .header {
- ...
- }
- /* Good example */
- .tweet {
- ...
- }
- .important {
- ...
- }
- .tweet-header {
- ...
- }
选择器
使用 classes 而不是通用元素标签来优化渲染性能.
避免在经常出现的组件中使用一些属性选择器 (例如,[class^="..."]). 浏览器性能会受到这些情况的影响.
减少选择器的长度, 每个组合选择器选择器的条目应该尽量控制在 3 个以内.
只在必要的情况下使用后代选择器 (例如, 没有使用带前缀 classes 的情况).
- /* Bad example */
- span {
- ...
- }
- .page-container #stream .stream-item .tweet .tweet-header .username {
- ...
- }
- .avatar {
- ...
- }
- /* Good example */
- .avatar {
- ...
- }
- .tweet-header .username {
- ...
- }
- .tweet .avatar {
- ...
- }
不要使用 @import
与 <link> 标签相比,@import 指令要慢很多, 不光增加了额外的请求次数, 还会导致不可预料的问题. 替代办法有以下几种:
使用多个 <link> 元素
通过 Sass 或 Less 类似的 CSS 预处理器将多个 CSS 文件编译为一个文件
语法
用两个空格来代替制表符(tab) -- 这是唯一能保证在所有环境下获得一致展现的方法.
在属性上, 使用双引号, 不要使用单引号.
不要在自动闭合标签结尾处使用斜线 - HTML5 规范 指出他们是可选的.
不要忽略可选的关闭标签(例如,</li> 和 </body>).
嵌套的节点应该缩进(四个空格).
字符编码
通过明确声明字符编码, 能够确保浏览器快速并容易的判断页面内容的渲染方式. 这样做的好处是, 可以避免在 HTML 中使用字符实体标记(character entity), 从而全部与文档编码一致(一般采用 UTF-8 编码).
引入 CSS 和 JavaScript
根据 HTML5 规范, 通常在引入 CSS 和 JavaScript 时不需要指明 type, 因为 text/CSS 和 text/JavaScript 分别是他们的默认值.
属性顺序
HTML 属性应该按照特定的顺序出现以保证易读性.
- class
- id
- name
- data-*
- src, for, type, href, value , max-length, max, min, pattern
- placeholder, title, alt
- aria-*, role
- required, readonly, disabled
Classes 是为高可复用组件设计的, 理论上他们应处在第一位. Ids 更加具体而且应该尽量少使用(例如, 页内书签), 所以他们处在第二位.
不要用 JavaScript 生成标签
在 JavaScript 文件中生成标签让内容变得更难查找, 更难编辑, 性能更差. 应该尽量避免这种情况的出现.
示例代码
- <!DOCTYPE HTML>
- <HTML lang="zh-CN">
- <head>
- <!-- External CSS -->
- <link rel="stylesheet" href="code-guide.css">
- <!-- In-document CSS -->
- <style>
- /* ... */
- </style>
- </head>
- <body>
- <a id="..." class="..." data-modal="toggle" href="#">
- Example link
- </a>
- <input class="form-control" type="text">
- <img src="..." alt="...">
- <!-- JavaScript -->
- <script src="code-guide.js">
- </script>
- </body>
- </HTML>
来源: http://www.bubuko.com/infodetail-3478653.html