前端开发文档规范

前端开发文档规划

基本原则

符合web标准（UTF-8，HTML5），语义化html（HTML5新增要求，减少div和span等无特定语义的标签使用），结构表现行为分离（HTML-CSS-JS代码分离，不同行为代码高内聚低耦合），兼容性优良（早期版本浏览器兼容，移动端和PC端设备兼容）.页面性能方面（减少请求次数，例如使用精灵图和sass语法），代码要求简洁明了有序，尽可能的减小服务器负载，保证最快的解析速度（减小repaint和reflow）.

文件命名规范

1、 html，css，js，lib，images文件均存放至项目的目录中。如果使用相关前端框架，根据框架的文件格式进行合理布局。

2、 所有文件夹及文件使用英文命名（避免使用中文路径）。

3、 html文件：入口文件使用index.html。如果有对应的设计组设计原稿，需要将对应的设计稿和html文件命名一致并合理存放。

4、 css文件命名：后缀.css。通用initial.css，初始化base.css，首页index.css，其他页面按照对应的html命名。

5、 Js文件命名：英文命名，后缀.js.通用common.js，初始化base.js。 其他页面按照对应的html命名。

HTML规范

1. 标签上属性的顺序建议如下：
   • class ( class 是为高可复用组件设计的,所以应处在第一位)
   • id name (id 更加具体且应该尽量少使用,所以将它放在第二位)
   • data-*
   • src for type href value
   • placeholder title alt
   • aria-* role
   • required readonly disabled
2. 非特殊情况下CSS文件放在body部分标签后。非特殊情况下大部分JS文件放在标签尾部（如果需要界面未加载前执行的代码可以放在head标签后）避免行内JS和CSS代码。
3. 所有编码需要遵循html（XML）标准，标签&属性&属性命名必须由小写字母及下划线数字组成，且所有标签必须闭合，包括br()，hr()等。属性值用双引号。
4. 引入JS库文件，文件名须包含库名称及版本号及是否为压缩版，

比如jquery-1.4.1.min.js。引入插件，文件名格式为库名称+插件名称，比如jQuery.bootstrap.js。

5. 尽量不使用选择器 （css3选择器）

举例：

<div class="content">
    <ul>
        <li>
            <a href=""></a>
            <a href=""></a>
            <a href=""></a>
        </li>
    </ul>
    <ul>
        <li>
            <a href=""></a>
            <a href=""></a>
            <a href=""></a>
        </li>
    </ul>
</div>

6. 书写代码前，提高样式重复使用率。

JS书写规范

1、变量命名：驼峰式命名.原生JS变量要求是纯英文字母，首字母须小写，

如myVue。jQuery变量要求首字符为'_'，其他与原生JS规则相同，如：_myVue。另，要求变量集中声明，避免全局变量.

2、类命名：首字母大写，驼峰式命名.如MyVue。

3、函数命名：首字母小写驼峰式命名.如myVue()。

4、 语言规范

• 声明变量必须加上 let 关键字.不要再使用 var
• 优先使用箭头函数
• 使用模板字符串取代连接字符串

5、使用分号
如果仅依靠语句间的隐式分隔,有时会很麻烦,使用分号更能清楚哪里是语句 的起止,而且有些情况下,漏掉分号会出 BUG

6、声明

var let const 应该放在function 已进入函数的时候
注释变量的功能及代表的含义,且应以字母顺序排序.每个变量单独占一行以便添加注释

举例：
var totalPrice = 1; //totalPrice表示商品购物车的总价 √
var num = 10,totalNum = 100 ; 不建议

7、回调函数统一使用 Promise 函数,回调成功的参数统一为 res,错误参数为 err

let callback = new Promise((resolve, reject) => {
    if ( 异步操作成功 ){
        resolve(value);
    } else {
        reject(err);
    }
});
callback.then((res) => {
    console.log('成功回调！', res);
}).catch((err) => {
    console.log('失败回调！', err);
});

8、尽量避免使用存在兼容性及消耗资源的方法或属性，比如eval_r()&innerText。

9、后期优化中，JS非注释类中文字符须转换成unicode编码使用，以避免编码错误时乱码显示。

10、代码结构明了，加适量注释.提高函数重用率。

11、注重与html分离，减小reflow，注重浏览器性能.