├── README.md ├── Standard ├── API规范.md ├── commint规范.md ├── js规范.md ├── 前端开发规范.md ├── 功能需求规范文档.md ├── 数据库设计规范.md ├── 文件规范.md └── 注释规范.md ├── Tutorial └── readme.md ├── blog ├── new_helpers.md └── readme.md ├── config └── .jshintrc ├── 开发须知.md ├── 笔戈软件开发流程.md └── 软件开发参与人员.md /README.md: -------------------------------------------------------------------------------- 1 | 笔戈开发相关文档 2 | ======== 3 | 4 | 5 | ## 开发规范 6 | 7 | * [API规范](Standard/API规范.md) 8 | * [JS规范](Standard/js规范.md) 9 | * [前端开发规范](Standard/前端开发规范.md) 10 | * [文件规范](Standard/文件规范.md) 11 | * [注释规范](Standard/注释规范.md) 12 | * [开发须知](开发须知.md) 13 | * [CSS&LESS开发规范](http://cxhtml.gitbooks.io/css-less-/content/) 14 | 15 | ## 培训汇总 16 | * [readme](readme.md) 17 | 18 | ## 软件文档 19 | 20 | 21 | ## 其他 22 | * [笔戈软件开发流程](笔戈软件开发流程.md) 23 | * [软件开发参与人员](软件开发参与人员.md) 24 | 25 | 26 | ------- 27 | 规范目前还不完善，需要持续改进 28 | -------------------------------------------------------------------------------- /Standard/API规范.md: -------------------------------------------------------------------------------- 1 | API规范用途 2 | 3 | 4 | 5 | ###API规范用途 6 | web应用开放的时候，常常同一个功能模块多个人开发。最常见的情况是前后端的工程师的合作，想象一个这样才场景 7 | 现在需要实现一个登录的功能， 8 | * 登录的时候，表单提交的url 是怎么样的， 9 | * 需要传递什么参数， 10 | * 密码错误时，用户被禁止登录时返回的状态码是怎么样的 11 | * 密码错误尝试次数太多 12 | 这些情况，如果不事先约定好一些状态码或者请求的url,前后端的交互就变变得很混乱，开放之前的API接口定义就变得 13 | 尤为重要。 14 | 15 | ###优点 16 | * 清晰的请求和数据交换格式 17 | * 编写API文档的同时，软件流程逻辑也会同时梳理 18 | * 及早地发现问题 19 | 20 | ### 路由API接口 21 | 22 | ####url 23 | 被请求的url地址 24 | 25 | ####url 功能描述 26 | 这个URL的功能 27 | 28 | ####请求方式 29 | get、post、put、delete 30 | 31 | ####是否需要登录 32 | 有些url 只有再登录后才能被访问， 默认为不需要登录， 33 | 34 | ####请求参数 35 | * name 36 | * 是否必须 37 | * 类型 38 | * 说明、默认值、可选值 39 | 40 | **Example** 41 | 42 | | name | 是否必须| 类型 | 说明，默认值，可选值等等| 43 | | ------------ | ------------- | ------------ |------------ | 44 | | Content Cell | Content Cell | Content Cell | Content Cell | 45 | 46 | ####返回结果 47 | 48 | json、或者文本、跳转等等说明 49 | 50 | ####返回字段说明 51 | 52 | **Example** 53 | 54 | | name | 是否必须| 类型 | 说明，默认值，可选值等等| 55 | | ------------ | ------------- | ------------ |------------ | 56 | | Content Cell | Content Cell | Content Cell | Content Cell | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 参考文档：[open.weibo.com](http://open.weibo.com/wiki/2/statuses/public_timeline) 64 | -------------------------------------------------------------------------------- /Standard/commint规范.md: -------------------------------------------------------------------------------- 1 | #写出好的 commit message 2 | 3 | ##为什幺要关注提交信息 4 | 5 | * 加快 Reviewing Code 的过程 6 | * 帮助我们写好 release note 7 | * 5年后帮你快速想起来某个分支，tag 或者 commit 增加了什么功能，改变了哪些代码 8 | * 让其他的开发者在运行 git blame 的时候想跪谢 9 | * 总之一个好的提交信息，会帮助你提高项目的整体质量 10 | 11 | ##基本要求 12 | * 第一行应该少于50个字。 随后是一个空行 第一行题目也可以写成：Fix issue #8976 13 | * 使用 fix（修复bug）, add（添加功能）, change（调整代码等） 而不是 fixed, added, changed 14 | * 永远别忘了第2行是空行 15 | * 用 Line break 来分割提交信息，让它在某些软件里面更容易读 16 | * 请将每次提交限定于完成一次逻辑功能。并且可能的话，适当地分解为多次小更新，以便每次小型提交都更易于理解。 17 | 18 | ## 例子 19 | 20 | ``` 21 | Fix issue #9527 22 | 23 | 小改直接就用一句话说清楚。 24 | 大改的，自己建一个 Issue 说清楚情况、方案、变化。。。。 25 | 其实最重要一点，commit log 是给人类看的，说清楚就好，不必太过拘谨，更不能写成只给机器看的东西。 26 | 27 | ``` 28 | 或者 29 | 30 | ``` 31 | Add feature #9527 32 | ``` 33 | -------------------------------------------------------------------------------- /Standard/js规范.md: -------------------------------------------------------------------------------- 1 | > 无论人数多少，代码都应该同出一门。 2 | 3 | #JavaScript 4 | 5 | ## 编码风格 JSHint 6 | 1. 在编辑器中，开启 JSHint 7 | 2. 在项目根目录建立 [.jshintrc 文件](../config/.jshintrc) 8 | 9 | ### 相关阅读 10 | [jshint](http://jshint.com/) 11 | 12 | 13 | ##Indentation,分号,单行长度 14 | * 一律使用2个空格 15 | * continuation-indentation 同样适用2个空格，跟上一行对齐 16 | >>>>>>> origin/master 17 | * Statement 之后一律以分号结束， 不可以省略 18 | * 单行长度，理论上不要超过80列，不过如果编辑器开启 soft wrap 的话可以不考虑单行长度 19 | * 接上一条，如果需要换行，存在操作符的情况，一定在操作符后换行，然后换的行缩进2个空格 20 | 这里要注意，如果是多次换行的话就没有必要继续缩进了，比如说右边第二段这种就是最佳格式。 21 | 22 | **Example** 23 | ``` 24 | if (typeof qqfind === "undefined" || 25 | typeof qqfind.cdnrejected === "undefined" || 26 | qqfind.cdnrejected !== true) { 27 | url = "http://pub.idqqimg.com/qqfind/js/location4.js"; 28 | } else { 29 | url = "http://find.qq.com/js/location4.js"; 30 | } 31 | ``` 32 | 33 | ##空行 34 | * 变量声明后（当变量声明在代码块的最后一行时，则无需空行） 35 | * 代码块后，逻辑块之间加空行增加可读性（在函数调用、数组、对象中则无需空行） 36 | * 单行或多行注释前加 37 | * 文件最后保留一个空行 38 | 39 | ##换行 40 | 换行的地方，行末必须有','或者运算符； 41 | 42 | 以下几种情况不需要换行： 43 | 44 | * 下列关键字后：else, catch, finally 45 | * 代码块'{'前 46 | 以下几种情况需要换行： 47 | 48 | * 代码块'{'后和'}'前 49 | * 变量赋值后 50 | 51 | 52 | ##变量命名 53 | * 标准变量采用驼峰标识 如: `ceseCamel` 54 | * 使用的ID的地方一定全大写，如：`userID` 55 | * 使用的URL的地方一定全大写, 比如说 reportURL 56 | * 涉及Android的，一律大写第一个字母 57 | * 涉及iOS的，一律小写第一个，大写后两个字母 58 | * 常量采用大写字母，下划线连接的方式，如：`NAMES_LIKE_THIS` 59 | * 构造函数，大写第一个字母 60 | * 类名驼峰，并且首字母要大写 CamelName 61 | * jquery对象必须以'$'开头命名 62 | 63 | ``` 64 | var thisIsMyName; 65 | 66 | var goodID; 67 | 68 | var AndroidVersion; 69 | 70 | var iOSVersion; 71 | 72 | var MAX_COUNT = 10; 73 | 74 | function Person(name) { 75 | this.name = name 76 | } 77 | ``` 78 | ##引号 79 | 最外层统一使用单引号。 80 | 81 | ``` 82 | // not good 83 | var x = "test"; 84 | 85 | // good 86 | var y = 'foo', 87 | z = '
'; 88 | ``` 89 | 90 | ##undefined使用场景 91 | * 永远不要直接使用undefined进行变量判断 92 | * 使用字符串 "undefined" 对变量进行判断 93 | 94 | 95 | ``` 96 | // Bad 97 | var person; 98 | console.log(person === undefined); //true 99 | 100 | // Good 101 | console.log(typeof person); // "undefined" 102 | ``` 103 | 104 | ##对象声明 105 | 106 | ``` 107 | // Bad 108 | var team = new Team(); 109 | team.title = "AlloyTeam"; 110 | team.count = 25; 111 | 112 | // Good semi colon 采用 符号后面接空格 的形式 113 | var team = { 114 | title: 'AlloyTeam', 115 | count: 25 116 | }; 117 | ``` 118 | 119 | ## 数组声明 120 | 121 | ``` 122 | Array Literals 123 | // Bad 124 | var colors = new Array("red", "green", "blue"); 125 | var numbers = new Array(1, 2, 3, 4); 126 | 127 | 128 | // Good 129 | var colors = [ "red", "green", "blue" ]; 130 | var numbers = [ 1, 2, 3, 4 ]; 131 | ``` 132 | 133 | ##括号对齐 134 | * 标准示例 括号前后有空格， 花括号起始 不另换行，结尾新起一行 135 | * 花括号必须要， 即使内容只有一行， 决不允许右边第二种情况 136 | * 涉及 if for while do...while try...catch...finally 的地方都必须使用花括号 137 | 138 | ##if else else前后留有空格 139 | ``` 140 | if (condition) { 141 | doSomething(); 142 | } else { 143 | doSomethingElse(); 144 | } 145 | ``` 146 | 147 | ##switch 148 | * 采用右边的格式， switch和括号之间有空格， case需要缩进， break之后跟下一个case中间留一个blank line 149 | * 花括号必须要， 即使内容只有一行 150 | ``` 151 | switch (condition) { 152 | case "first": 153 | // code 154 | break; 155 | 156 | case "third": 157 | // code 158 | break; 159 | 160 | default: 161 | // code 162 | } 163 | ``` 164 | 165 | ##for 166 | * 普通for循环, 分号后留有一个空格， 判断条件等内的操作符两边不留空格， 前置条件如果有多个，逗号后留一个空格 167 | * for-in 一定要有 hasOwnProperty 的判断， 否则 JSLint 或者 JSHint 都会有一个 warn 168 | 169 | ``` 170 | var values = [ 1, 2, 3, 4, 5, 6, 7 ], 171 | i, len; 172 | 173 | for (i=0, len=values.length; i` | 段落 20 | `

...` | 标题 21 | `