前端开发规范【范本】

2024-02-06 14:42:52

概述

为提高团队协作效率，规范文件管理，方便项目后期维护，提高代码质量，特制订此文档，前端开发人员必须遵照本规范进行前台页面开发。

一、目录规范

1. 页面存放目录

文件夹命名均首字母大写

|--@root
    |--Member //业务模块名
        |--Conf
        |--Controller //存放控制器
        |--Veiw //存放页面
            |--Basic  //PC终端
            |--Mobile //手机终端
                |--Index //控制器名
                    |--index.php //页面
|--README.md

页面引用静态文件时，引用静态文件输出目录路径。详见3
__ASSET__为PHP常量，定义静态文件输出目录为dev或dist可在develop.php文件中查看。

2.静态文件存放目录

所有文件及文件夹命名均为小写

|--@root
    |--dist //存放编译后文件，用于测试
    |--dev  //存放编译后文件，用于开发；详见**3.静态文件输出目录**
        |--basic
        |--mobile
    |--libs   //第三方插件+
    |--tmp //存放在页面中使用的图片，一般为可以后台上传的图片,页面调用路径为__PUBLIC__tmp/
        |--index_index //页面文件夹
    |--src  //存放源码文件
        |--basic
        |--mobile //以mobile目录为例，basic目录同理
            |--common //存放mobile终端下公用文件
                |--images    //存放图像文件
                |--css       //存放css文件
                |--common.js //js文件直接存放在common文件夹下
            |--index 
            |--member //业务模块名
                |--common//业务公共模块
                    |--css
                    |--js
                    |--index.js
                |--index_index //命名规范：控制器名_页面名（与HTML文件命名相同）；存放页面私有文件
                    |--images
                        |--image.png
                    |--index.css
                    |--index.js
        |--common //跨终端公共组件
|--package.json
|--webpack.config.dist.js //配置源文件，复制后重命名为webpack.config.js使用
|--README.md  //项目介绍

3. 静态文件输出目录

webpack自动编译输出，除tmp文件夹下可添加图片外勿在此文件夹下添加任何文件
|--@root
    |--dist //输出同开发目录
    |--dev
        |--basic
        |--mobile
            |--images //存放图片
            |--member //业务模块名
                |--common.min.css
                |--index_index.min.css
                |--index_index.min.js
                |--index_index.min.css.map //.map为源码映射文件,dist目录下不输出
                |--index_index.min.js.map
            |-ensure //异步加载文件

二、命名规范及注释规范

命名规范

此规范为图片命名规范，html、css文件命名规范请参照目录规范

图片的名称分为头尾两部分，用减号-隔开，头部分表示此图片的大类性质

banner-* //放置在页面顶部的广告、装饰图案等长方形的图片
logo-*   //标志性的图片
btn-*-*  //在页面上位置不固定并且带有链接的小图片；命名规范：btn-功能名-大小/私有
pic-*    //装饰用的照片
tit-*    //不带链接表示标题的图片
icon-*   //一系列图标图片

鼠标感应效果：图片名+on/off；例如：icon-list-on.png,icon-list-off.png

文本缩进

（重要）统一使用 2 个空格缩进，不得使用 tab 和 4 个空格

注释

重中之重，已加入绩效考核指标
更新代码后即时更新注释
注释是你自己与你的小伙伴们了解代码写法和目的的唯一途径。特别是在写一些看似琐碎的无关紧要的代码时，由于记忆点不深刻，注释就变得尤为重要了。

当你写注释时一定要注意：不要写你的代码都干了些什么，而要写你的代码为什么要这么写，背后的考量是什么。当然也可以加入所思考问题或是解决方案的链接地址。

1. 在文件开始时写块注释：

/** 
 * 作用于哪些页面
 * 注明代码业务/功能说明
 * @authors Your Name (you@example.org)
 * @date    2016-05-16
 * @version $Id$
 */
// 单行注释添加一个空格
var offset = 0; // 此处注明变量注释

if(includeLabels) {
  // If the labels are included we need to have a minimum offset of 20 pixels
  // We need to set it explicitly because of the following bug: 
  // http://somebrowservendor.com/issue-tracker/ISSUE-1
  offset = 20;
}

模块功能描述说明

/**
 * ------------------------------------------------------------------
 * 模块描述说明
 * ------------------------------------------------------------------
 */

模块内的小函数方法归类：

/**
 * 小函数方法归类说明，这些零散的小函数方法放在一起 对应 一个业务方法逻辑
 * ------------------------------------------------------------------
 */

单个函数注释

/**
 * 函数功能简述
 *
 * 具体描述一些细节
 *
 * @param    {string}  address     地址
 * @param    {array}   com         商品数组
 * @param    {string}  pay_status  支付方式
 * @returns  void
 *
 * @date     2014-04-12
 * @author   QETHAN<qinbinyang@zuijiao.net>
 */

2. css注释的写法：

/* Footer */

内容区

/* End Footer */

关注点分离

理解 web 中如何和为何区分不同的关注点，这很重要。这里的关注点主要指的是：信息（HTML 结构）、外观（CSS）和行为（JavaScript）。为了使它们成为可维护的干净整洁的代码，我们要尽可能的将它们分离开来。
严格地保证结构、表现、行为三者分离，并尽量使三者之间没有太多的交互和联系。
就是说，尽量在文档和模板中只包含结构性的 HTML；而将所有表现代码，移入样式表中；将所有动作行为，移入脚本之中。
在此之外，为使得它们之间的联系尽可能的小，在文档和模板中也尽量少地引入样式和脚本文件。
清晰的分层意味着：
不使用超过一到两张样式表i.e. main.css, vendor.css
不使用超过一到两个脚本（学会用合并脚本）
不使用行内样式.no-good {}
不在元素上使用 style 属性``
不使用行内脚本alert('no good')
不使用表象元素i.e. , , , ,
不使用表象 class 名red, left, center

三、CSS规范

目前沿用NEC规范，阅读本规范前请熟读 NEC规范

补充规范

阅读 CSS编码规范
补充规范是指在NEC规范上扩展的规范，部分示例中有不符合NEC规范的，以NEC规范为准。

请熟读以上规范条例，在工作中严格遵守。

四、JS规范

基本规范

sublime Text3请安装jshint插件以检查JS编写错误;
安装教程：使用lint进行语法及风格校验

异步加载文件命名

require.ensure([],function(){
    //异步加载内容
},'ensure/业务模块名_页面名_异步方法名_1')

引号
最外层统一使用单引号。

// not good
var x = "test";

// good
var y = 'foo',
    z = '<div id="test"></div>';

空行
以下几种情况需要空行：
变量声明后（当变量声明在代码块的最后一行时，则无需空行）
注释前（当注释在代码块的第一行时，则无需空行）
代码块后（在函数调用、数组、对象中则无需空行）
文件最后保留一个空行

// need blank line after variable declaration
var x = 1;

// not need blank line when variable declaration is last expression in the current block
if (x >= 1) {
    var y = x + 1;
}

var a = 2;

// need blank line before line comment
a++;

function b() {
    // not need blank line when comment is first line of block
    return a;
}

// need blank line after blocks
for (var i = 0; i < 2; i++) {
    if (true) {
        return false;
    }

    continue;
}

var obj = {
    foo: function() {
        return 1;
    },

    bar: function() {
        return 2;
    }
};

// not need blank line when in argument list, array, object
func(
    2,
    function() {
        a++;
    },
    3
);

var foo = [
    2,
    function() {
        a++;
    },
    3
];


var foo = {
    a: 2,
    b: function() {
        a++;
    },
    c: 3
};

变量声明
一个函数作用域中所有的变量声明尽量提到函数首部，用一个var声明，不允许出现两个连续的var声明。

function doSomethingWithItems(items) {
    // use one var
    var value = 10,
        result = value + 10,
        i,
        len;

    for (i = 0, len = items.length; i < len; i++) {
        result += 10;
    }
}

函数

无论是函数声明还是函数表达式，’(‘前不要空格，但’{‘前一定要有空格；
函数调用括号前不需要空格；
立即执行函数外必须包一层括号；
不要给inline function命名；
参数之间用’, '分隔，注意逗号后有一个空格

// no space before '(', but one space before'{'
var doSomething = function(item) {
    // do something
};

function doSomething(item) {
    // do something
}

// not good
doSomething (item);

// good
doSomething(item);

// requires parentheses around immediately invoked function expressions
(function() {
    return 1;
})();

// not good
[1, 2].forEach(function x() {
    ...
});

// good
[1, 2].forEach(function() {
    ...
});

// not good
var a = [1, 2, function a() {
    ...
}];

// good
var a = [1, 2, function() {
    ...
}];

// use ', ' between function parameters
var doSomething = function(a, b, c) {
    // do something
};

数组、对象

对象属性名不需要加引号；
对象以缩进的形式书写，不要写在一行；
数组、对象最后不要有逗号。

// not good
var a = {
    'b': 1
};

var a = {b: 1};

var a = {
    b: 1,
    c: 2,
};

// good
var a = {
    b: 1,
    c: 2
};

变量命名规范

标准变量采用驼峰式命名
ID在变量名中全大写
URL在变量名中全大写
Android在变量名中大写第一个字母
iOS在变量名中小写第一个，大写后两个字母
常量全大写，用下划线连接
构造函数，大写第一个字母
jquery对象必须以$开头命名

var thisIsMyName;

var goodID;

var reportURL;

var AndroidVersion;

var iOSVersion;

var MAX_COUNT = 10;

function Person(name) {
    this.name = name;
}

// not good
var body = $('body');

// good
var $body = $('body');

前缀规范

s：表示字符串。例如：sName，sHtml;
n：表示数字。例如：nPage，nTotal;
b：表示逻辑。例如：bChecked，bHasLogin;
a：表示数组。例如：aList，aGroup;
r：表示正则表达式。例如：rDomain，rEmail;
f：表示函数。例如：fGetHtml，fInit;
o：表示以上未涉及到的其他对象，例如：oButton，oDate;

例外情况：

1：作用域不大临时变量可以简写，比如：str，num，bol，obj，fun，arr。
2：循环变量可以简写，比如：i，j，k等。

函数命名规范

统一使用动词或者动词[+名词]形式，例如：fGetVersion()，fSubmitForm()，fInit();涉及返回逻辑值的函数可以使用is，has等表示逻辑的词语代替动词。

如果有内部函数，使用__f+动词[+名词]形式，内部函数必需在函数最后定义。

对象方法实现
对象方法命名使用 f+对象类名+动词[+名词]形式;例如 fAddressGetEmail

事件响应函数
某事件响应函数命名方式为触发事件对象名+事件名或者模块名+触发事件对象名+事件名，例如：fDivClick()，fAddressSubmitButtonClick()

其它注意事项

所有命名最好使用英语表示。
所有变量名应该明确而必要，尽量避免不必要的容易混淆的缩写。
netease.events.mouse.Handler，而不是 netease.events.mouse.MouseEventHandler。
对应的方法应该使用对应的动词，例如：get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end。
应该避免双重否定意义的变量，例如：bIsNotError, bIsNotFound，不可取。
变量应该在最小的范围内定义，并尽可能的保持最少的活动时间。
循环变量最好在循环中定义。例如for(var i=0,m=10;i++)
尽量避免复杂的条件语句，可以使用临时的boolean变量代替。
一定要避免在条件中执行语句，例如：if((i=3)>2){}，不可取。
不要在代码中重复使用相同意义的数字，用一个变量代替

码农公寓

概述