PHP编码规范之注释和文件结构说明


Posted in PHP onJuly 09, 2010

文件结构

|??images
|??include

|??parameter

|??config

|??function
|??index
images存放图片文件,include中是系统是要引用的文件,一般在parameter中存放参数文件,config中存放配置文件,function中存放方法文件,如javascript的方法等,并按功能模块的分类,将各功能的类也放入其中
文件名
文件夹命名一般采用英文,长度一般不超过20个字符,命名采用小写字母。除特殊情况才使用中文拼音,一些常见的文件夹命名如:images(存放图形文件),flash(存放Flash文件),style(存放CSS文件),scripts(存放Javascript脚本),inc(存放include文件),link(存放友情链接),media(存放多媒体文件)等。文件名称统一用小写的英文字母、数字和下划线的组合。
块注释
块注释通常用于提供对文件,方法,数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方,比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。
块注释之首应该有一个空行,用于把块注释和代码分割开来,比如:
/*
 * 这里是块注释
*/
块注释可以以/*-开头,这样indent(1)就可以将之识别为一个代码块的开始,而不会重排它。
/*-
 * 如果想被忽略,可是使用特别格式的块注释
 *
 * one
 *

two
 *

three
 */
注意:如果你不使用indent(1),就不必在代码中使用/*-,或为他人可能对你的代码运行indent(1)作让步。
单行注释
短注释可以显示在一行内,并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完,就该采用块注释。单行注释之前应该有一个空行。以下是一个代码中单行注释的例子:
if (condition) {

/* 以下代码运行的条件 */

...
}
尾端注释
极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中,它们应该具有相同的缩进。
以下是一个代码中尾端注释的例子:

if ($a == 2) { 
return TRUE; /* 对单一条件的说明 */ 
} else { 

return isPrime($a); /* 其余的条件 */ 
}

行末注释
注释界定符"//",可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本;然而,它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子:
if ($foo > 1) { 
// 第二种用法. 

... 
} 
else { 

return false; // 说明返回值的原因 
} 
//if ($bar > 1) { 
// 
//  // 第三种用法 
//  ... 
//} 
//else { 

// return false; 
//}

文档注释
文档注释描述php的类、构造器,方法,以及字段(field)。每个文档注释都会被置于注释定界符/**...*/之中,一个注释对应一个类或成员。该注释应位于声明之前:

/**
 * 说明这个类的一些 ...
*/
class Example { ...

注意顶层(top-level)的类是不缩进的,而其成员是缩进的。描述类的文档注释的第一行(/**)不需缩进;随后的文档注释每行都缩进1格(使星号纵向对齐)。成员,包括构造函数在内,其文档注释的第一行缩进4格,随后每行都缩进5格。
若你想给出有关类、变量或方法的信息,而这些信息又不适合写在文档中,则可使用实现块注释(见5.1.1)或紧跟在声明后面的单行注释(见5.1.2)。例如,有关一个类实现的细节,应放入紧跟在类声明后面的实现块注释中,而不是放在文档注释中。
文档注释不能放在一个方法或构造器的定义块中,因为程序会将位于文档注释之后的第一个声明与其相关联。

PHP 相关文章推荐
php GD绘制24小时柱状图
Jun 28 PHP
PHP简洁函数小结
Aug 12 PHP
采集邮箱的php代码(抓取网页中的邮箱地址)
Jul 17 PHP
php通过array_unshift函数添加多个变量到数组前端的方法
Mar 18 PHP
PHP实现将textarea的值根据回车换行拆分至数组
Jun 10 PHP
php算法实例分享
Jul 14 PHP
CI框架简单邮件发送类实例
May 18 PHP
PHP登录验证码的实现与使用方法
Jul 07 PHP
Yii使用DeleteAll连表删除出现报错问题的解决方法
Jul 14 PHP
PHP编程计算文件或数组中单词出现频率的方法
May 22 PHP
PHP中的浅复制与深复制的实例详解
Oct 26 PHP
thinkPHP3.2使用RBAC实现权限管理的实现
Aug 27 PHP
PHP中开发XML应用程序之基础篇 添加节点 删除节点 查询节点 查询节
Jul 09 #PHP
php set_magic_quotes_runtime() 函数过时解决方法
Jul 08 #PHP
PHP 函数学习简单小结
Jul 08 #PHP
PHP 5.3.1 安装包 VC9 VC6不同版本的区别是什么
Jul 04 #PHP
PHP三层结构(上) 简单三层结构
Jul 04 #PHP
Apache 配置详解(最好的APACHE配置教程)
Jul 04 #PHP
PHP中文URL编解码(urlencode()rawurlencode()
Jul 03 #PHP
You might like
PHP接收json 并将接收数据插入数据库的实现代码
2015/12/01 PHP
laravel 时间格式转时间戳的例子
2019/10/11 PHP
Laravel框架实现抢红包功能示例
2019/10/31 PHP
PHP 对象继承原理与简单用法示例
2020/04/21 PHP
JQuery团队打造的javascript单元测试工具QUnit介绍
2010/02/26 Javascript
JQUERY设置IFRAME的SRC值的代码
2010/11/30 Javascript
Javascript的getYear、getFullYear、getUTCFullYear异同分享
2011/11/30 Javascript
js工具方法弹出蒙版
2013/05/08 Javascript
jQuery之过滤元素操作小结
2013/11/30 Javascript
JQuery性能优化的几点建议
2014/05/14 Javascript
5种处理js跨域问题方法汇总
2014/12/04 Javascript
freemarker判断对象是否为空的方法
2015/08/13 Javascript
html+js+highcharts绘制圆饼图表的简单实例
2016/08/04 Javascript
Vue 中批量下载文件并打包的示例代码
2017/11/20 Javascript
微信小程序实现图片上传、删除和预览功能的方法
2017/12/18 Javascript
深入理解nodejs搭建静态服务器(实现命令行)
2019/02/05 NodeJs
React+TypeScript+webpack4多入口配置详解
2019/08/08 Javascript
Vue执行方法,方法获取data值,设置data值,方法传值操作
2020/08/05 Javascript
[01:07:02]DOTA2-DPC中国联赛 正赛 iG vs PSG.LGD BO3 第三场 2月26日
2021/03/11 DOTA
详解Python中的__init__和__new__
2014/03/12 Python
python解析基于xml格式的日志文件
2017/02/25 Python
Python生成随机数组的方法小结
2017/04/15 Python
python中is与双等于号“==”的区别示例详解
2017/11/21 Python
Django使用redis缓存服务器的实现代码示例
2019/04/28 Python
详解Python的循环结构知识点
2019/05/20 Python
python中 * 的用法详解
2019/07/10 Python
PyTorch学习:动态图和静态图的例子
2020/01/06 Python
Python如何利用Har文件进行遍历指定字典替换提交的数据详解
2020/11/05 Python
纯CSS3绘制打火机动画火焰效果
2016/07/18 HTML / CSS
QA工程师岗位职责
2013/11/20 职场文书
库房主管岗位职责
2013/12/31 职场文书
《春晓》教学反思
2014/04/20 职场文书
副乡长民主生活会个人对照检查材料思想汇报
2014/10/01 职场文书
写给医院的感谢信
2015/01/22 职场文书
经理岗位职责范本
2015/04/15 职场文书
导游词之安徽巢湖
2019/12/26 职场文书