1. PHP 编码规范培训
研发部总监：徐江涛
Contact@shjuto at gmail.com
Work @ Telligem.com
Life @ Nanchang

2. 主题：程序开发的编码规范
为什么需要代码规范
phpDocumentor简介
phpDoumentor tags 讲解
它山之石、可以攻玉
总结&提问

3. 为什么需要代码规范
初次接触者的疑虑：程序的功能，性能无疑是最重要
的，设计也很重要，为什么却要把这么多的精力放在
代码规范上呢，仅仅是为了方便别人阅读代码，便于
维护吗?这样一套套的代码规范真的可以加快开发速度
吗?
当开发人员很好的遵守代码规范来编写代码时，才
可以慢慢的体会到规则，才会体会到设计。可以想
像一下，如果遵守代码规范，一个方法不得超出50
行代码，那么大量的if else就不可能出现，取而代
之以各种设计（如工厂，策略等设计模式）来解决
问题
一个高手写的代码应该是容易看懂的，这也是大道至简的精髓所在

4. phpDocumentor简介
PHPDocumentor是一个用PHP写的工具，对于有规范注
释的php程序，它能够快速生成具有相互参照,索引等功
能的API文档。老的版本是phpdoc，从1.3.0开始，更名
为phpDocumentor，新的版本加上了对php5语法的支
持，同时，可以通过在客户端浏览器上操作生成文档，
文档可以转换为PDF,HTML,CHM几种形式，非常的方便。
PHPDocumentor工作时，会扫描指定目录下面的php源
代码，扫描其中的关键字，截取需要分析的注释，然后
分析注释中的专用的tag，生成xml文件，接着根据已经
分析完的类和模块的信息，建立相应的索引，生成xml
文件，对于生成的xml文件，使用定制的模板输出为指
定格式的文件。

5. phpDocumentor tags

6. phpDocumentor tags
@abstract
Document an abstract class, class variable or
method
/**
* example of basic @abstract usage in a class
* Use this if every single element of the class is abstract
* @abstract
*/
class myabstractclass
{
function function1($baz)
{
...
}
function function2()
{
...
}
}

7. phpDocumentor tags
@access
Access control for an element. @access private prevents
documentation of the following element (if enabled).
* This is possible, but redundant. An element has @access public by default
* @access public
*/
class class1
{
/**
* all text in this DocBlock will be ignored, unless command-line switch
* @access private
*/
var $private_var;
/**
* Protected is allowed, but does absolutely nothing.
* @access protected
*/
/**
* this function is documented
*/
function publicmethod()
{
}
}

8. phpDocumentor tags
@author
Author of current element
/**
* Page-Level DocBlock example.
* displays as Gregory Beaver<strong>cellog@php.
net</strong>
* , where underlined text is a "mailto:cellog@php.net" link
* @author Gregory Beaver <cellog@php.net>
*/
/**
* function datafunction
* another contributor authored this function
* @author Joe Shmoe
*/
function datafunction()
{
...
}

9. phpDocumentor tags
@category
Specify a category to organize the documented element's package
into
/**
* Page-Level DocBlock
* @package MyPackage
* @category mycategory
*/
/**
* @global array used for stuff
*/
function mine()
{
global $baz;
...
}

10. phpDocumentor tags
@deprecated
Document elements that have been deprecated and should not be used as
they may be removed at any time from a future version
/**
* @deprecated deprecated since version 2.0
*/
function uselessfunction()
{
...
}
/**
* also legal
* @deprecated
*/
class stupidclass
{
...
}

11. phpDocumentor tags
@example
Include an external example file with syntax
highlighting
/**
* My function
*
* Here is an inline example:
* <code>
* <?php
* echo strlen('6');
* ?>
* </code>
* @example /path/to/example.php How to use this function
* @example anotherexample.
inc This example is in the "examples" subdirectory
*/
function mine()
{
}

12. 它山之石、可以攻玉
<?php
$a=100;
$b=1000;
$c=$a+$b;
<?php
$a = 100;
$b = 1000;
$c = $a + $b;
?>
运算符 、函数括号 必须空 1格

13. 它山之石、可以攻玉
$query = “SELECT FirstName, LastName FROM employees, departments WHERE
employees.dept_id = department.dept_id AND department.Name = ‘Engineering’”;
$query = “ SELECT FirstName,LastName
FROM
employees,departments
WHERE
employees.dept_id = department.dept_id
AND
department.Name = ‘Engineering’”
SQL语句的指导写法

14. 它山之石、可以攻玉
<?php
if(isset($name))
echo “Hello $name”;
?>
<?php
if(isset($name))
echo “Hello $name”;
$known_user = true;
?>
<?php
if(isset($name)) {
echo “Hello $name”;
}
else {
echo “Hello Stranger”;
?>
注意使用if语句

15. 它山之石、可以攻玉
（BSD style） BSD风格
if ($condition)
{
// statement
}
（GNU style）GNU 风格
if ($condition)
{
// statement
}
（K&R style）K&R风格
if ($condition) {
// statement
}
采用 BSD 或是 GUN风格

16. 它山之石、可以攻玉
避免使用全局变量
全局变量看起来是个非常不错的东西，但你在任何地方都可以修改它，
因此从安全和效能方面来讲你需要避免使用。
在很多情况下你需要使用全局变量；比如数据库的链接，为了避免访问
一应用程序产生多个数据库链接,可能你会选择使用全局变量
但其实在这种情况下你可以选择使用单例模式来化解这个问题。
<?php
$US_STATES = array(‘Alabama’, … , ‘Wyoming’);
?>
<?php
function us_states()
{
static $us_states = array(‘Alabama’, … , ‘Wyoming’);
return $us_states;
}

17. 它山之石、可以攻玉
合理的命名，多个词组成的变量命名
$numElements = count( $elements );
//更好的便于理解的方式：
$num_elements = count( $elements );
避免使用短标记
<?
echo ‘helloworld’ ;
?>
<?php
echo ‘helloworld’;
?>

18. Thank you!