0%

Web开发规则

succes

精神

  • 代码优雅,可读性高。
  • 注释内容简明扼要。
  • 绝对不能写死程序。
  • 不留不要用的、垃圾程序代码。
  • 其他内容看详情。

Git

  • Master 的 版本必须是最稳定的版本。
  • 每次 Commit 信息应该如实填写,不可模棱两可。
  • 禁止 上传 IDE 的 project data。

分支 (Branch)

  • 命名规则:应以此分支主要目的命名 (修复BUG、新增某特定功能)。
  • 不可出现版本号、文件名、档目录信息。
  • 合并后的分支应删除。

Restful

  • URL中不应该包含动词。
  • URL的结尾不应该包含 ‘/’(有‘/’和无‘/’表示的资源是不同的)。
  • URL中的正斜杠 ‘/’必须用于表达层次关系。
  • URL中应该使用‘-’连接单词提高可读性,而不是‘_’。
  • URL路径中首选小写字母。
  • URL路径中的名称应使用复数形式(除非资源为唯一资源)。

命名

  • 命名应根据内容做有意义的命名,让后续维护人员可以一目了然!

  • 即使不会发生错误,程序代码英文大小写也需明确区分。

  • 我自己的标准是:

    1. 绝对不可使用没有意义的命名。
    2. 变量和函数命名最好是(动词+名词:setName、getId或者set_name、get_id等等)。
    3. 资源命名最好是(使用下划线区分:nav_logo.png等等)。
    4. css id、class命名最好是(名词短语,以 - 隔开:user-id等等)。

语意

类型命名规则说明
属性 (Attribute, Property)名词
user_name、userName
方法 (Method, Function)动词+名词
getUserName、get_user_name
常见的动词有:get、set、update、delete、remove

不管使用以上哪种规则,在开发同一个项目时,必须使用同一种规则,严禁混用。

注意:我自己是这样使用的:在JavaScript中,属性、变量和方法命名都使用字母大小写区分的方式;在php中,变量和方法命名使用下划线区分的方式。但是,在面向对象编程中,class中,全部使用字母大小写区分,类名的所有单词首字母大写,并且文件名即类名。

附加表

类型面向对象中动词使用数据库METHOD(restful)
增-CREATEadd/createINSERTGET
查-READget/listSELECTPOST
改-UPDATEset/replace/edit/addUPDATEPUT/PATCH
删-DELETEremove/deleteDELETEDELETE

字母与分隔

语言变量 (Variable, Parameter, Argument)常数 (Constant)面向对象 - 类名 (Class Name)面向对象 - 成员 (mebmer)
HTML、CSS全部小写,不同单字以「-」分隔
user-id
JavaScript首字小写,不同单字「首字以大写」分隔
userId
全部大写,不同单字以「_」分隔
MAX_COUNT
首字大写,不同单字「首字以大写」分隔
一个文件放一个 Class
文件名即为 Class Name
User
公有 (public) : 首字小写,不同单字「首字以大写」分隔
name, getName
私有 (private): _公有命名规则
_name, _getName
PHP全部小写,不同单字以「_」分隔
user_id
SQL由使用者定义的:表名、字段名
全部小写,不同单字以「_」分隔
SQL语法、函数
全部大写
SELECT、INSERT INTO

通用

  • 程序代码编写
  • 每个函数应该注释,注释应包含函数功能说明、自变量说明。
  • 不必要的代码不要写,也禁止放到注释里面!
  • if-else 的 {} 严禁省略。
  • {} 起始一律跟在前一个功能的最后,禁止换行

正确写法

1
2
3
4
5
6
public function test(){
//do something
if($a === $b){
//do something
}
}

错误写法

1
2
3
4
5
6
7
8
public function test()
{
//do something
if($a === $b)
{
//do something
}
}
  • 程序代码排版
    • 任何程序代码应该以 2 个 space 为一个阶层做好排版、不可使用 tab。
  • 函数 (Function, Methd)
    • 函数声明时需在函数上方加上函数注释,注释应包含函数说明、自变量内容 (自变量类型、自变量英文名称、自变量说明)、 回传值内容 (回传值类型、回传值说明)
  • 类 (Class)
    • 一个类 (Class) 的声明只能存在一个文件。
    • 类 (Class) 的声明文件,文件名必须为类名。
  • 其他
    • 链接本地任何其他资源 (图片、文件、网站) 皆使用相对路径,禁止使用绝对路径,非本地资源除外。

HTML

程序代码编写

  • 禁止在 HTML 使用 <style><script>,一律使用外部文件引用方式引用 CSS、JavaScript文件。
  • HTML 标签需成双成对,有头有尾。
  • 区块标签:<tag></tag>
  • 单标签:<tag />
  • 禁止使用已被 HTML 舍弃的旧标签、属性,如:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    <!-- html tag -->
    <center>
    <font>
    <basefont>
    <s>
    <strike>
    <u>
    <listing>
    <plaintext>
    <xmp>
    <!-- html attribute -->
    align
    bgcolor
    color

CSS

程序代码编写

CSS 的定义应该独立一个 CSS 文件,禁止使用 <style>style 属性直接在 HTML 中定义样式。(js也是一样。)

就算是自己本身写测试代码,使用 "<style>" 或者 "<script>" 也应该明确写出 "[type]" 属性。

JavaScript

程序代码编写

  • 禁止使用 HTML 字符串,一律使用 Dom 产生 HTML
  • 禁止省略箭头函数 (Arrow function) 的括号
    正确
    1
    2
    3
    a = (a, b) => {
    c;
    }
    错误 (这是允许的,但造成程序代码阅读困难,故禁止)
    1
    a  => c;

注释

JavaScript 注释应该遵循 JSDoc 的标准编写

全局变量 (Global)

1
/* global $t, Tiger */

常数 (Constant)

1
2
3
4
/**
* 常数说明
* @type {常数类型}
*/

Example

1
2
3
4
5
/**
* 使用者ID
* @type {String}
*/
var userId = 'Hello';

函数、方法 (Function, Method)

1
2
3
4
5
6
7
/**
* 函数用途说明
* @param {自变量类型} 自变量名称 自变量说明
* @param {自变量类型} [选择性自变量名称] 自变量说明
* @param {自变量类型} [选择性自变量名称=自变量默认值] 自变量说明
* @returns {回传值类型} 回传值说明
*/

Example

1
2
3
4
5
6
7
8
9
10
11
/**
* 取得使用者
* @param {Int} userId 使用者ID
* @param {Object} [options] 其他选项
* @param {String} [options.query='a'] 查询关键词 默认为 a
* @returns {Object} 用户数据
*/
var getUser = function(userId, options){
//do something
return user;
};

另外补充一点,在调试Js代码后,通常要强制刷新后才有效。在Js中,通常使用一些方法或者css属性时,有 "-" 的应该改为后面第一个单词字母大写。(例:font-weight=>fontWeight)

PHP

前端参数取得

参数取得需透过 filter_input 函数取得,不得使用 $_GET、 $_POST

输出到前台

参数命名必须为:全部小写,不同单字以「_」分隔
方法命名相同。

注释

PHP 注释应该遵循 PHPDoc 的标准编写

成员变数 (Member)

成员变量只的是 Class 内的成员变量,我们都会要求替成员变量增加注释说明。通常 Function 的变量除非太特别否则都不需要特别注释说明。

1
2
3
4
/**
* 成员变量说明
* @type {类型}
*/

Example

1
2
3
4
5
/**
* 使用者ID
* @type {String}
*/
$userId = 'Hello';

函数、方法 (Function, Method)

1
2
3
4
5
6
7
/**
* 函数用途说明
* @param 自变量类型 自变量名称 自变量说明
* @option 自变量选项类型 自变量选项名称 自变量选项说明
* @uses 全局变量 全局变量说明
* @returns 回传值类型 回传值说明
*/

Example

1
2
3
4
5
6
7
8
9
10
11
12
/**
* 取得使用者
* @param int userId 使用者ID
* @param object options 其他选项
* @option string options['query'] 查询关键词
* @uses $_POST['role_id'] 从前端以POST取得角色ID
* @returns object 用户数据
*/
function getUser($userId, $options){
//do something
return $user;
};

Database

  • 禁止使用 Table Join。
  • 禁止使用 Oracle Trigger。
  • 禁止将查询数据库的 SQL 放在循环中查询

    SQL 编写

  • 属于 SQL 语法使用大写 (SELECT, WHERE, INSERT etc..)
  • 属于使用者自己定义的使用小写 (表名 table name, 字段名 column name etc..)
  • 表名、字段名前后需加上 `
  • *Example**
    1
    INSERT INTO `user` VALUES('a', 'b');

统一用词

仅为举例,不限于此。碰到问题,再行商榷。

用词统一
最后最后
关闭
离开
Cancel
取消
存储
储存
修改
保存
搜寻
搜索
Search
查询
OK
确认
Confirm
确定
移除
Remove
Delete
删除
bulb