基于 Angularjs 项目的编码风格约定总结

真正写这个的原因是因为项目中乱七八糟的代码实在是太让人无语了。甚至有人用a,b,c这种完全无意义的参数名，很多时候我对中国的程序员想的可能太理想了，尤其是在前端，一大堆从静态页面转过来的所谓的程序员，他们缺少必要的编程素养甚至连

技术追求都没有，换句话说就是欠调教。

编码风格约定

写在最前面

一个统一的好的编码风格好过一打大牛
你怎么看别人的代码呢？

每个人都有自己的编码风格，这个受到个人的学习以及工作历程影响。多人协同开发，不可避免的会遇到一个功能几个人一起开发，或者同一个功能，前后由不同的人开发。这个时候问题来了，如果是你，你会怎么看待别人的代码呢？呵呵，这其实已经不言

而喻了。

那又怎么样？

说实话对于个人来说，真不能怎么样，谁没有一两个满是坑的项目呢，又有谁不是从最开始的垃圾代码中慢慢提炼出自己的编码风格呢。但是对于一个项目，那太可怕的，不会有人会想要遇到这样的项目，很多人会在项目风险爆发之前溜之大吉，留下满地狼

藉，等待重建。但是你真的希望你自己的项目，亲手写的代码，最后会是这样的结果？或者当你进入一家新公司的时候，竟然拿不出一点可以用来的炫耀的东西。

我们要怎么做？

如果每一回看到别人的代码都痛不欲生，那么我们的人生还有什么快乐。你要相信你不会永远只关注于你自己的一个小角落。那么我们要怎么做呢？如果你能看别人的代码如同你自己的写的，你写的代码每一行都是犹如ISO般的标准，那么是不是会有这样的

感觉：“我靠，我当初怎么这么傻”。这就是我们现在要做的，统一编码风格：不同的人写一样风格的代码，对应业务处理有着相同的代码逻辑。

约定大于规范

讲了这么多，只是为了阐述统一编码风格的重要。在这里我需要提出这样一个概念：约定大于规范，及凡是在约定范围里的内容，必须被不折不扣的实行，否则我们的这些约定又有什么意义呢。

期待以后更多的约定

现在定义的这些肯定不会是全部，在以后的开发中必然会遇到更多的问题，从而提炼出更多的约定，这是好事情，也是正确的方向。让我们满怀期待这样盼望。

编码风格约定

BB了半天，让我们进入正题，这篇文档既是这次代码重构的指导文档，也会是前端小组的内部代码规范定义文档，用来给每一个新加入的兄弟姐妹们套上一个足够结实的辔头，以约束你们过于奔放的想法，编程毕竟是一个严谨的工作。

命名规范及约定

这项本来是不想说的，但是作为未来前端代码规范文档，这里还是需要提一下。禁止一切无意义命名，禁止全局变量的定义，rootScope中的变量需要统一在app.js中定义。

变量命名

变量的命名，首先是这肯定是一个名词，禁止使用中文拼音以及拼音缩写。遵循小驼峰命名，首字符小写。scope底下禁止独立变量的存在。

var isBoolean = true; //布尔值以is开头
var arrayList = []; //数组以List结尾
$scope.type = 1; /**这种写法是禁止使用的**/

函数命名

函数一般是执行一组操作的代码块，所以用动名词结合的方式命名，使用var name = function(agrs)。函数内部需要用到一些关键参数，作为入参传入，即使在scope中存在，也需要作为入参传入（好处是提高函数复用的可能）。当前项目中不需要

匿名函数（回调函数除外），以及自运行函数。

var getSomting = function(id){} //获取某个值
var loadSomting = function(agrs[]){} //从后台加载数据，涉及到restService
var postSomting = function(obj{}){} //提交表单操作，新建
var deleteSomting = function(id){} //删除操作
var putSomting = function(id,obj{}){} //提交表单操作，修改
var initSomting = function(){} //初始化函数，一般是用来获取某个获取后台的某个资源

$scope.views = {
showSomting : function(){}
chooseSomting : function(){}
}

全局静态常量定义约定

这里的全局常量需要定义在单独的appstatic.js文件下，方便统一管理以及协同开发。定义一个全局的常量约定如下：命名：全大写英文，用下划线""分割单词定义方法： constant() 或者 value()

angular.module('myApp.static', [])
.constant("USER_TYPE",{1:"个人",2:"企业"})

全局动态变量定义约定

全局的动态变量来自后台提供的一些业务数据，大部分来自数据库字典表，这里使用factory的定义service的方式来实现全局动态变量的定义，约定如下：命名：全大写英文，用下划线"_"分割单词定义方法： factory

angular.module('myApp.somting',[])
.factory("SOME_TYPES", function ($resource) {
var SOME_TYPES= {};
$resource(url, 'GET').then(function (result) {
SOME_TYPES= result
});
return SOME_TYPES;
})

注释约定

注释是用来解释当前代码的功能，一个好的注释就是能让人一眼看懂复杂的内部实现逻辑，而一个规范的注释能够形成最后的api文档。当然最重要的是注释可以你知道究竟该找谁痛扁一顿，所以凡写过必留下痕迹。

文件注释

写在文件的最开头

/**
* @author
* @date
* @module name
* @description
*/

controller注释

写在controller内部第一行

.controller(function(){
/**
* @author
* @date
* @controller name
* @description
*/
})

函数注释

写在函数外面，入参和出参如果没有就不要写

/**
* @fuction name
* @param {agr[0]:"描述",agr[1]:"描述"}
* @return {agr[0]:"描述",agr[1]:"描述"}
* @description
* @author
* @date
*/
function(){
return ;
}

行注释

单行注释

var obj = "" ; //参数定义注释
function(){
...
// 对函数内部代码或者逻辑的特殊说明
...
}

代码顺序的约定

代码顺序既是对于controller中的N多行代码究竟谁先谁后的约定。

顺序依次是：

1.scope变量定义在最前；

2.controller中的局部变量其次（即使实际使用的函数在其他位置）；

3.scope底下的function；

4.controller内部函数；

5.初始化函

数定义及调用注：只要是在scope中用到的变量全部需要最先声明。

.controller(function(){
/*scope底下的对象最先声明*/
$scope.somting = {};
/*controller局部变量*/
var somting;
/*scope底下的function*/
$scope.doSomting = function(){}
/*controller局部函数*/
var doSomting = function(){}
/*controller的初始化函数定义*/
var initSomting = function(){}
/*运行初始化函数*/
initSomting();
})

基础数据模型定义的约定

基础数据模型依赖于后台接口提供的数据，同时根据前台具体的业务场景或不变或转换格式保存在前台缓存对象下，同时也可以将变化过的数据更新到当前数据模型中。

app.factory("userService",function($resource){
var userList = []; //将userList数据本地化
var getList = function(){//来自后台数据}
var get = function(id,callback){//来自后台数据}
var update = function(id,user,callback){//来自后台数据}
var delete= function(id,callback){//来自后台数据}

//本地处理函数
var _setUser = function(id,user){//userList.set}
var _removeUser = function(id,user){//userList.remove}
var _getUser = function(id,user){//userList.get}

return {
getUserList: function(){
if(userList) {
return userList ;
}else {
return getList();
}
},
getUserById: function(id,callback){
get(id,callback);
},
updateUserById: function(id,user,callback){
update(id,user,callback)
},
deleteUserById: function(id,callback){
delete(id,callback);
}
}
})

试图模型定义的约定

controller中的离散变量将通过scope.views（作为试图模型对象）统一控制，甚至某些复杂页面视图模型，可以在views中用单独的对象处理。

//页面视图控制数据模型
$scope.views = {
somting : "",
isSomting : true,
chooseSomting : function(){
this.sonting = "";
},
oneObj:{
oneType : "",
showOne : fucntion(){
this.one = "";
}
}
}

//后台返回数据模型
$scope.somting = somtingService.get();

业务数据模型定义的约定

业务数据模型一般是有别于基础数据模型和视图数据模型，一般是包含视图内容的数据对象，例如表单数据对象，或者被选中的某些数据，这些数据一般用于界面控制也会提取出接口参数用于交互。

$scope.views = {
somting : "",
isSomting : true,
chooseSomting : function(){
this.sonting = "";
},
oneObj:{
oneType : "",
showOne : fucntion(){
this.one = "";
}
}
}