16.5 文件和代码规范
最后更新于：2022-04-02 00:22:59
## 通用注释
### 1. 文件的注释通用样例（普通程序文件，类文件，函数文件，变量定义文件）
~~~
/**
* XXXXX的文件
*
* 功能1： xxx
* 功能2： xxx
*
* @file $Source: /home/doc/php开发注释规范.md $
* @package core
* @author Joy
* @version $Id: php开发注释规范.txt,v 1.1 2014/03/04 20:37:46 Joy Exp $
* @link http://www.joychao.cc
*/
~~~
* @package 是团队事先定义好的，在phpdocumentor里同一package的文件可以给出跟踪的链接。项目开发前需要对其定义。
* @link 行后面接的地址是程序开发文档的地址，因为我们目前没有在线的程序开发文档库，所以可不加。 注意注释的排版，左端保持对齐。
**说明：以上自动更新版本及文件名需要配置svn，具体请自行google 'SVN自动版本号'**
### 2. 普通函数注释
~~~
/**
* 获取头像地址
*
* @author Joy
*
* @param string $imageName 图片文件名
* @param integer $size 大小
*
* @return string
*/
function getAvatarUrl($imageName, $size = 80)
{
return sprintf(SITE_URL . '/service/images/cropped_%s/'.$imageName, $size);
}
~~~
顺序按照author、param、return来放，区块间空行。
### 3. 程序段落注释
段落注释和逻辑注释使用如下方式
~~~
/**
* 1 如果$_GET['do']等于buy,则购买条码
*/
if($_GET['do'] == 'buy')
{
// 1.1 验证用户提交变量是否合法
if($_POST['strCodeNum'])
{
}
// 1.2 验证用户提交的码是否可以购买
// 1.3 ..................
} // end if
/**
* 2 如果$_GET['do']等于list,显示用户选择的条码
*/
if($_GET['do'] == 'list')
{
// 2.1 验证用户提交变量是否合法
if($_POST['strCodeNum'])
{
}
// 2.2 验证用户提交的码是否可以购买
// 2.3 ..................
} // end if
~~~
';