Home | 简体中文 | 繁体中文 | 杂文 | 打赏(Donations) | ITEYE 博客 | OSChina 博客 | Facebook | Linkedin | 知乎专栏 | Search | About

1.7. 标准与规范

1.7.1. Release Notes

Release Notes 撰写说明

当一个项目升级时,需要写一个文档纪录这次变动,内容包括,新增了什么,更改了什么,修复了什么,未解决得问题,改善了什么,忽略了什么

常用信息类型

		
New
Changed
Fixed
Unresolved
Improved
Ignore
		
		

例 1.1. Example - Release Notes

			
NEW - xxxxxxxxxxxxx
CHANGED - xxxxxxxxxxxxx
FIXED - xxxxxxxxxxx
UNRESOLVED - xxxxxxxxx
IMPROVED - xxxxxxxxx
			
			

你也同样可以参考很多开源组织编写的Release Notes,例如apache, mysql, php 等等

1.7.2. Project directory

一种很蠢目录规划:

			project
			project/library
			project/log
			project/tmp
			project/...
		

目录规划原则,临时文件分离,日志分离,配置文件分离;这样有利于在负载均衡环境中克隆节点。

  • 项目目录/workspace/project

  • 临时目录 /workspace/tmp/

  • 日志 目录/workspace/log/

  • 配置文件/workspace/conf

1.7.3. 版本控制及如何运作

1.7.3.1. 版本库布局

版本库布局

  1. trunk
  2. branches
  3. tags
  4. releases

多项目版本库布局

			
		 	                   /-> branches
		       .---> project 2 ---> trunk
		      / 	           \-> tags
		     /
		    /					/-> branches
repositories -------> project 1 ---> trunk
			\ 					\-> tags
			 \
			  \ 			   /-> branches
			   `---> project 3 ---> trunk
				               \-> tags
				
		

1.7.3.2. 策略

trunk 主干,作为主干你要保证他的代码是可运行的。

branches 分支,代码来自主干,可以有很多分支,分支用于多个团队同步开发,最终要将代码合并到主干。例如:branches/member, branches/blog, branches/shop 分别来自不同的团队

tags 一般用于做快照,一旦建立永不更改

releases 发行本版,代码来自主干, 与tags功能一样,命名更直观。例如每个月为一个周期,发布一次代码 releases/v1.0, releases/1.5

			
                          .-----------------------------------------------------------------------> cart r100 ---> ...
                         /		                                                                          ^
                        .----------------------> blog r3 ---> r4 ... ... r(10) ---> r(n) ---> r(...) --->/---> ...
                       /		                   ^                        \                           /
               .-> branches r1  ---> member r2 ---/---------> r4 ... r(10) --\----> r(14) ---> r(...)--/---> ...
              /                       ^          /                \           \         \             /
repositories ----> trunk    r1  -----/----------/--------------> r(11) ---> r(12) ---> r(15) ---> r(...) ---> ...
              \	                                                                \         \          \
               `-> tags     r1  ------------------------------------------> v1.0.0 r(13)   \          \
                       \                                                                               \
                        `--------------------------------------------------------------> v1.0.1 (r16)   \
                         `--------------------------------------------------------------------------> v1.0.2 r(n)
			
		

			
                                                                            .> unstable 2.1.1
                          		                                           / \
                                              unstable 1.1           unstable 2.1     unstable 3.1
                        		                  ^ \                     ^ \         / \
               .-> branches ---> unstable 1.0 ---/   \   unstable 2.0 ---/   \   unstable 3.0    unstable---> ...
              /                      ^                \            ^          \      ^    \          ^
repositories ----> trunk    --------/-----------------> stable ---/-----> stable ---/---> stable ---/-> stable ---> ...
              \	                                       \                     \              \
               `-> tags     ----------------------------> stable 1.0          \              \
                       \                                                       \              \
                        `-------------------------------------------------------> stable 2.0   \
                         `-------------------------------------------------------------------> stable 3.0
			
		

怎样访问版本库

美工、页面人员采用WebDav访问Subversion。Photoshop,Dreamwaver 软件对WebDav有很好地支持,他们不需要学习如何使用Subversion。

开发者通过Svn客户端访问代码库,既可以使用开发IDE集成工具也可以使用单独工具。像TortoiseSVN等等。

1.7.3.3. nightly version

每天晚上做一个快照

1.7.3.4. rc1,rc2,rc4

1.7.3.5. 怎样写注释信息

1.7.3.5.1. Fixed Bug
				svn ci -m "- Fixed bug #53412 (your comment)"
			
1.7.3.5.2. Implemented
				svn ci -m "- Implemented FR #53271, FR #52410 (Building multiple XXXX binary)"
			
1.7.3.5.3. Add
				svn ci -m "- Add Feature #534 (your message)"
			

1.7.4. 代码审查

Code Review

一对一代码审查可以提高程序质量.

		

developer neo ---> coding ---> commit --->.
                           /               \
developer zen ---> review '                 \
                                           --->  svn repos
developer neo ---> review .                 /
                           \               /
developer zen ---> coding ---> commit --->`
		
		

1.7.4.1. Coding workflow

1.7.5. Redis Key

Redis Key 使用“:”分割例如

set SMS:CAPTCHA 1234
		

1.7.6. 错误编码

格式 ABCD

A: 编码

1 用户错误

2 网络错误

3 系统错误

4 应用服务器错误

5 应用程序错误

6 缓存错误

7 数据库错误

8 搜索引擎

B 编码

0 成功

1 失败

剩余 C D 用户自行编码

1.7.7. HTML 标准

1.7.7.1. 校验

https://html5.validator.nu/?doc=https%3A%2F%2Fwww.netkiller.cn%2Findex.html	
		

1.7.7.2. XHTML/HTML

1.7.7.3. CSS

1.7.7.4. Script

1.7.8. 编码风格

https://code.google.com/p/google-styleguide/
http://lxr.linux.no/linux/Documentation/CodingStyle
http://perldoc.perl.org/perlstyle.html
http://www.gnu.org/prep/standards/
	

1.7.8.1. java 编程规范

1.7.8.1.1. Spring Data JPA
			
	@Autowired
	private TableRepostitory tableRepostitory;
	
	@Autowired
	private JdbcTemplate jdbcTemplate;
	
	@PersistenceContext 
	private EntityManager entityManager; 
			
			

1.7.8.2. php 文件

http://www.php-fig.org

1.7.8.2.1. 格式与 编码

使用 UNIX 风格换行, 请在你的编辑器内调整

UNIX (LF或"\n")
MAC OS (CR 或"\r")
Windows CRLF \r\n
			

源码文件使用 UTF-8

有些IDE环境 UTF-8 BOM

1.7.8.2.2. 循环嵌套

if, while, for, foreach, do ... loop, switch... 等的嵌套必须小于等于3层

如下面的例子,可读性极差。

if (xxx){
	if (xxx){
		if(xxx){
			if(xxx){
				if(xxx){

				}
			}
		}
		if(xxx){
			if(xxx){
			}
		}
	}
	if (xxx){
		if(xxx){
			if(xxx){
			}
		}
		if(xxx){
			if(xxx){
			}
		}
	}
}
			

加以改造

func aaa(p){
	if(p){
		if(xxx){
		}
	}
}
func bbb(b){
	if(b){
		if(xxx){
			if(xxx){

			}
		}
	}
}

if(xxx){
	aaa(xxx)
}
if(b){
	bbb(b)
}			
1.7.8.2.3. 取出行尾的空格以及多余的换行符

一个空格占用一个字节,换行符Window是两个字节\r\n, Unix与Mac占用一个字节

1.7.8.2.4. php 标签

禁止这样使用

			
<?
...
?>
			
			

正确的使用方法

			
<?php
...

or

<?php
...
?>
			
			
1.7.8.2.5. 头部注释
			
<?php
/**
 * Project Name
 *
 * @author     $Author: netkiller $
 * @copyright  Copyright (c) 2012 Company
 * @version    $Id: chapter.coding.xml 584 2013-05-15 05:13:17Z netkiller $
 */

<?php
/**
 * Project Name
 *
 * @author     $Author: netkiller $
 * @license    GNU General Public License 2.0
 * @version    $Id: chapter.coding.xml 584 2013-05-15 05:13:17Z netkiller $
 */
			
			

1.7.8.3. String

双引号要处理字符串转义,性能上不如单引号,如果你不需要转义字符串,或者字符串中不含原转译字符,建议你使用单引号

print("string")
		

每次输出会检索特殊字符串如: \r, \n, \t, \0xFF 等等

print('string')
		

1.7.8.4. Database

使用pdo_mysql替代mysql

错误的写法,通过字符串链接拼接sql语句极容易出现注入漏洞

$sql = "select * from table where id=".$id;
$sql = "select * from table where id='".$id."'";
$sql = "INSERT INTO fruit(name, colour) VALUES ('".$name."', '".$colour."')";
		

正确的写法

$sql = "select * from table where id=?";
$sql = "INSERT INTO fruit(name, colour) VALUES (?, ?)";
		
		
$sql = <<<____SQL
     CREATE TABLE IF NOT EXISTS `ticket_hist` (
       `tid` int(11) NOT NULL,
       `trqform` varchar(40) NOT NULL,
       `trsform` varchar(40) NOT NULL,
       `tgen` datetime NOT NULL,
       `tterm` datetime,
       `tstatus` tinyint(1) NOT NULL
     ) ENGINE=ARCHIVE COMMENT='ticket archive';
____SQL;
		
		
1.7.8.4.1. 结果集使用注意事项

返回数据库查询结果有几种形式

数组形式

			
Array
(
    [0] => banana
    [1] => yellow
)

Array
(
    [NAME] => banana
    [COLOUR] => yellow
)
			
			

对象形式

Object
(
	Obj->NAME
	Obj->COLOUR
)
			

正确的使用方式

print($row[name])
print($row->name)
			

错误的使用使方式

print($row[0])
			

避免使用 "*"查询,一会影响性能,二增加带宽开销

$sql = "select * from tab where status=0 limit 1";
			

如果程序使用$row[1]读取结果,有可能当数据库结构改变,增加字段,字段顺序发生变化,输出数据都会出错

1.7.8.4.2. 索引

下面的例子,不会使用索引

$sql = "select id, name, created from tab where id != 100";
			
EXPLAIN select * from members where id != '1010';			索引失效
EXPLAIN select count(*) from members where id != '1010';	索引有效
			
1.7.8.4.3. 缓存

			

下面的例子,数据不会缓存查询结果

$sql = "select id, name, created from tab where created=now()";
			

1.7.9. 安全

1.7.9.1. Interface

1.7.9.2. SQL注入