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 修复未正常关闭的HTML标签实现代码(支持嵌套和就近闭合)
Jun 07 PHP
PHP5权威编程阅读学习笔记 附电子书下载
Jul 05 PHP
PHP中UNIX时间戳和日期间的转换与计算实例
Nov 19 PHP
php递归实现无限分类的方法
Jul 28 PHP
PHP响应post请求上传文件的方法
Dec 17 PHP
crontab无法执行php的解决方法
Jan 25 PHP
php中array_column函数简单实现方法
Jul 11 PHP
php计算给定日期所在周的开始日期和结束日期示例
Feb 06 PHP
php获取目录中所有文件名及判断文件与目录的简单方法
Mar 04 PHP
php ajax数据传输和响应方法
Aug 21 PHP
PHP图像处理 imagestring添加图片水印与文字水印操作示例
Feb 06 PHP
yii 框架实现按天,月,年,自定义时间段统计数据的方法分析
Apr 04 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
分享3个php获取日历的函数
2015/09/25 PHP
yii插入数据库防并发的简单代码
2017/05/27 PHP
PHP实现的XXTEA加密解密算法示例
2018/08/28 PHP
限制复选框的最大可选数
2006/07/01 Javascript
JS 参数传递的实际应用代码分析
2009/09/13 Javascript
js事件(Event)知识整理
2012/10/11 Javascript
jquery在Chrome下获取图片的长宽问题解决
2013/03/20 Javascript
在JavaScript里嵌入大量字符串常量的实现方法
2013/07/07 Javascript
node.js中的events.emitter.listeners方法使用说明
2014/12/10 Javascript
JavaScript点击按钮后弹出透明浮动层的方法
2015/05/11 Javascript
js生成随机数的过程解析
2015/11/24 Javascript
jQuery插件开发精品教程让你的jQuery提升一个台阶
2016/01/27 Javascript
BootStrap制作导航条实例代码
2016/05/06 Javascript
js中遍历对象的属性和值的方法
2016/07/27 Javascript
响应式表格之固定表头的简单实现
2016/08/26 Javascript
如何在AngularJs中调用第三方插件库
2017/05/21 Javascript
vue项目中公用footer组件底部位置的适配问题
2018/05/10 Javascript
使用Webpack提升Vue.js应用程序的4种方法(翻译)
2019/10/09 Javascript
js模拟实现百度搜索
2020/06/28 Javascript
vue实现自定义多选按钮
2020/07/16 Javascript
Python __setattr__、 __getattr__、 __delattr__、__call__用法示例
2015/03/06 Python
python MySQLdb Windows下安装教程及问题解决方法
2015/05/09 Python
python原类、类的创建过程与方法详解
2019/07/19 Python
python-Web-flask-视图内容和模板知识点西宁街
2019/08/23 Python
django自带调试服务器的使用详解
2019/08/29 Python
解决torch.autograd.backward中的参数问题
2020/01/07 Python
Python 解决火狐浏览器不弹出下载框直接下载的问题
2020/03/09 Python
Nordgreen美国官网:在线购买极简主义斯堪的纳维亚手表
2019/07/24 全球购物
英国和国际包裹递送:ParcelCompare
2019/08/26 全球购物
Overload和Override的区别
2012/09/02 面试题
三月学雷锋活动总结
2014/06/26 职场文书
初三语文教学计划
2015/01/22 职场文书
保留意见审计报告
2015/06/05 职场文书
出生证明范本
2015/06/15 职场文书
为什么代码规范要求SQL语句不要过多的join
2021/06/23 MySQL
Android使用EventBus发送消息,Fragment中接收消息的方法会执行多次
2022/04/24 Java/Android