维生数后台规范_v1.1

发表于 | 分类于 | 阅读次数
维生数工作室后台组规范

1. 代码基本格式

  • 缩进使用4个空格，以兼容各种编辑器。如vim默认tab缩进8个空格，.vimrc配置tab缩进为4个空格
  • class, function间必须有层次关系
  • 各模块之间必须有1行间隔，如：各function之间间距 1 行
  • 大中小括号{ [ ( ) ] }，括号外围加空格间隔,等号”=”左右必须有空格隔开
  • 逗号 “,” 后空一格
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php // 以php为例
namespace test;
use testFunction; // 注意空行
class test
{
    function model1( param1, param2 ) // 注意空格
    {
        // your code
    }   // 注意空行
    function model2( param1, param2 )
    {
        // your code
    }
}

if

  • if小括号接大括号”{“,else if/else同上，请在大括号后加上条件注释,判定条件过多可用switch语句
    1
    2
    3
    4
    5
    6
    7
    if (conditions) { // 这里记得注释条件
        // your code    
    } else if (conditions) { // 这里记得注释条件
        // your code
    } else {
        // your code
    }

switch

  • 需要加上参数描述，以及条件注释
    1
    2
    3
    4
    5
    6
    7
    8
    switch (param) { // 参数描述
        case 1: // 条件注释
            // your code
        case 2:
            // your code
        default：
            // your code
    }

key-value格式

  • 数组、json对象需要赋值时，请根据情况适当使用回车键，方便查找、更改、注释
    1
    2
    3
    4
    5
    <?php
    $test = array( // 此时使用array而不是用中括号
        '1' => 'a',
        '2' => 'b'
    );
1
2
3
4
5
// js
var test = {
    test1: 'test1',
    test2: 'test2'
};

2. 注释规范

  • 单行注释统一在代码后空一格写注释，块注释星号后要空格

    1
    2
    3
    /* 块注释占用一行或多行 */
    $example = 'example'; // 这是个例子

  • 每个function前必须有功能描述以及作者和联系方式

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    /**
     * 测试用  <--此处为功能描述
     * @author xxx xxx@email.com <--作者、联系方式
     * @param {*} param1 括号填上参数类型
     * @param {*} param2 括号填上参数类型
     */
    function test( param1, param2 )
    {
        // your code
    }

  • 在更改别人的代码时，请注释标明更改者、联系方式、更改时间、更改区域，使用块注释注释原来代码，请勿删除原代码

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    /**
     * 测试用  <--此处为功能描述
     * @author xxx xxx@email.com <--作者、联系方式
     * @param {*} param1 括号填上参数类型
     * @param {*} param2 括号填上参数类型
     */
    function test( param1, param2 )
    {
        /* echo '原代码'；*/
        // @editor xxx, edited_time:1970.1.1 
        // start>>>
        echo 'hello World'; 
        // <<<end
    }

3. 命名规范

变量命名

  • 命名使用 驼峰命名法

    1
    2
    3
    4
    function PrintHelloWorld() // 类使用大驼峰命名法
    {
        $testData = 'hello world'; // 变量使用小驼峰命名法
    }

  • 常量全部大写

  • 命名要求准确地表达变量意义，不能过度缩写，如意义相同使用下划线+数字方法区分变量
    1
    2
    3
    4
    5
    var n; // 错
    var num; // 看情况
    var number; // 对
    var num_1 = '1';
    var num_2 = '2';

数据库及字段命名

  • 表名各单词间使用下划线连接,小写
  • 字段命名使用用下划线区分单词，小写

4. 代码功能要求

  • 需要处理相同逻辑时，代码不应重复出现
  • ”一行代码能解决的事就不用两行“

  • 统一接口返回格式为

    1
    2
    3
    4
    5
    { // js
        code: 200,
        message: 'ok'
        data: 'data here'
    }

  • 每次协作开发前统一code

  • 后台能解决的事情别要求前端去解决

5. 接口文档编写规范

文档的编写也是开发过程之一，在完成代码部分后，一份好的文档直接向别人展示了你的水平。接口文档你可以用Markdown来写，也可以用office来写。Markdown语法参考

接口文档要求接口功能描述清晰、参数完整，可读性强，对接时推荐使用表格形式，以下为基本要求

接口名称 url 请求方式 请求参数 返回参数 备注
登录 login post username, password 200，500 测试

返回参数应提供一个示例

1
2
3
4
5
{
    code: 200,
    message: 'ok'
    data: 'data here'
}

  • 文档命名时请自定义版本号，文档内容标注好日期以及撰写人

    6. 协作要求

  • 熟练使用git
  • 必须使用git控制版本，完成某个任务后，提交代码至仓库请为每个改动文件添加变动描述
  • 分模块协作时，自创建不同分支完成不同模块后，再提交合并，以防代码冲突和覆盖
  • 善用worktile、trello等等协作工具，微信交流方便，但是易忘、不方便总结
  • 严禁在服务器直接更改、上传代码

2017.08.23 by 古毅