PHP编码规范之注释和文件结构说明
文件结构
|――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编码规范
为什么我们要培养自己的编码规范? 我们写代码的时候,一个好的编码规范,对我们来说能够起到很多意向不到的效果.至少会有一下的好处: 1.提高我们的编码效率.整齐划一的代码方便我们进行复制粘贴嘛! 2.提高代码的可读性. 3.显示我们专业.别人看到了我们的代码,发现整个代码的书写流程都整齐划一,瞬间逼格就上去了! 4.方便团队协同工作.大家使用同一的规范,这样就消除了五花八分的书写方式,同一协调! 编码规范包含两大块,代码规范和注释规范 其实我们所写的php脚本,其实也就是由两大块组成的,即对代码的
-
PHP编码规范-php coding standard
目录 介绍 标准化的重要性 解释 认同观点 项目的四个阶段 命名规则 合适的命名 缩写词不要全部使用大写字母 类命名 类库命名 方法命名 类属性命名 方法中参数命名 变量命名 引用变量和函数返回引用 全局变量 定义命名 / 全局常量 静态变量 函数命名 php文件扩展名 文档规则 评价注释 Comments Should Tell a Story Document Decisions 使用标头说明 Make Gotchas Explicit Interface and Implementatio
-
PHP符合PSR编程规范的实例分享
前言 关于开发标准这块,可以说一直都是风格迥异,各家都有各家的玩法,民间更是个人玩个人的.目前我们国内比较出名的几个框架(Yii,Laravel) 都已经支持Composer并且加入了PHP-FIG(php框架程序组). 其中Composer的自动加载就支持PHP-FIG指定的PSR-0 和 PSR-4 规范来实现自动加载机制,并且Composer推荐使用PSR-4 PHP-FIG 这是一个自愿非正式的机构,但是就目前对我们的影响来看,可能都已经默认为一个公信组织了,的的确确制定了不少非常好的规
-
PHP编码规范的深入探讨
缩进与空白字符(Indenting and Whitespace)使用 2 个空格而不使用 tab 键进行代码缩进(notepad++, Eclipse 等编辑器均支持此项配置);行尾不应该有空白字符应使用 \n (Unix换行符),而不是 \r\n (Windows 换行符)所有文件均应以一个空行结尾 运算符(Operators)所有二元运算符(二个值之间的运算符),如 +, -, =, !=, ==, > 等等,在运算符两端均需留有一个空格,如应该使用 $foo = $bar 而不是 $fo
-
讲的非常不错的PHP编码规范第1/3页
注:这是从PHPCMS开发文档里看到编码规范,虽名为PHPCMS的开发规范,但我觉得所有的PHP编程都该如此.写了那么多PHP,很多编码对照这规范都感觉欠缺很多,今后一定要对照纠正. Phpcms 编码规范 1. 引言-. 2 2. 适用范围-. 2 3. 标准化的重要性和好处-. 3 4. PHP编码规范与原则-. 3 4.1. 代码标记- 3 4.2. 注释- 3 4.3. 书写规则- 4 4.3.1. 缩进- 4 4.3.2. 大括号{}.if和switch. 4 4.3.3. 运算符.小
-
PHP的PSR规范中文版
文档仓库地址:https://github.com/hfcorriez/fig-standards PSR规范中文版 PSR-0自动加载 PSR-1基本代码规范 PSR-2代码样式 PSR-3日志接口为何规范 摘录翻译了官方的一句话 本组织旨在通过讨论我们代码项目的共同点以找出一个协作编程的方法. 在此想到了一篇文章<Google为何要执行严格的代码规范>中有这么一段话: 复制代码 代码如下: 在谷歌,我可以查看任何的代码,进入所有谷歌的代码库,我有权查看它们.事实上,这种权限是很少人能拥有的
-
php 注释规范
@access 使用范围:class,function,var,define,module 该标记用于指明关键字的存取权限:private.public或proteced @author 指明作者 @copyright 使用范围:class,function,var,define,module,use 指明版权信息 @deprecated 使用范围:class,function,var,define,module,constent,global,include 指明不用或者废弃的关键字 @exa
-
PHP Document 代码注释规范
1. 什么是phpDocumentor ? PHPDocumentor 是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档.老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便. PHPDocumentor工作时,会扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释
-
PHP文件注释标记及规范小结
PHP 注释标记 @access 使用范围:class,function,var,define,module 该标记用于指明关键字的存取权限:private.public或proteced @author 指明作者 @copyright 使用范围:class,function,var,define,module,use 指明版权信息 @deprecated 使用范围:class,function,var,define,module,constent,global,include 指明不用或者废弃
-
PHP编码规范之注释和文件结构说明
文件结构 |――images |――include |――parameter |――config |――function |――index images存放图片文件,include中是系统是要引用的文件,一般在parameter中存放参数文件,config中存放配置文件,function中存放方法文件,如javascript的方法等,并按功能模块的分类,将各功能的类也放入其中 文件名 文件夹命名一般采用英文,长度一般不超过20个字符,命名采用小写字母.除特殊情况才使用中文拼音,一些常见的文件夹命
-
浅谈JavaScript编程语言的编码规范
JavaScript 编程语言作为最流行的客户端脚本语言,早已被众多 Web 开发人员所熟悉.随着 Web2.0 时代的到来和 Ajax 技术的广泛应用,JavaScript 也逐渐吸引着更多的视线.工作中要求越多的是对 JavaScript 语言的深入学习,灵活运用,和对编码质量的保证. 对于熟悉 C/C++ 或 Java 语言的工程师来说,JavaScript 显得灵活,简单易懂,对代码的格式的要求也相对松散.很容易学习,并运用到自己的代码中.也正因为这样,JavaScript 的编码规范也
-
浅谈Android编码规范及命名规范
前言: 目前工作负责两个医疗APP项目的开发,同时使用LeanCloud进行云端配合开发,完全单挑. 现大框架已经完成,正在进行细节模块上的开发 抽空总结一下Android项目的开发规范:1.编码规范 2.命名规范 注:个人经验,经供参考 一.Android编码规范 1.学会使用string.xml文件 在我看来,当一个文本信息出现的次数大于一次的时候就必须要使用string.xml 比如一个保存按钮 , 不规范写法: <Button android:id="@+id/editinfo_b
-
Python 常用 PEP8 编码规范详解
Python 常用 PEP8 编码规范 代码布局 缩进 每级缩进用4个空格. 括号中使用垂直隐式缩进或使用悬挂缩进. EXAMPLE: # (垂直隐式缩进)对准左括号 foo = long_function_name(var_one, var_two, var_three, var_four) # (悬挂缩进) 一般情况只需多一层缩进 foo = long_function_name( var_one, var_two, var_three, var_four) # (悬挂缩进) 但下面情况,
-
Python 编码规范(Google Python Style Guide)
Python 风格规范(Google) 本项目并非 Google 官方项目, 而是由国内程序员凭热情创建和维护. 如果你关注的是 Google 官方英文版, 请移步 Google Style Guide 以下代码中 Yes 表示推荐,No 表示不推荐. 分号 不要在行尾加分号, 也不要用分号将两条命令放在同一行. 行长度 每行不超过80个字符 以下情况除外: 长的导入模块语句 注释里的URL 不要使用反斜杠连接行. Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你可以利用这
-
python 编码规范整理
一 代码编排 1 缩进4个空格的缩进(编辑器都可以完成此功能),不要使用Tap,更不能混合使用Tap和空格. 2 每行最大长度79,换行可以使用反斜杠,最好使用圆括号.换行点要在操作符的后边敲回车. 3 类和top-level函数定义之间空两行:类中的方法定义之间空一行:函数内逻辑无关段落之间空一行:其他地方尽量不要再空行. 二 文档编排 1 模块内容的顺序:模块说明和docstring-import-globals&constants-其他定义.其中import部分,又按标准.三方和自己编写顺
-
JAVA程序员不得不留意的编码规范
01 规范存在的意义 应用编码规范对于软件本身和软件开发职员而言尤为重要,有以下几个原因: 好的编码规范可以尽可能的减少一个软件的维护本钱 , 并且几乎没有任何一个软件,在其整个生命周期中,均由最初的开发职员来维护: 好的编码规范可以改善软件的可读性,可以让开发职员尽快而彻底地理解新的代码: 好的编码规范可以最大限度的进步团队开发的合作效率: 长期的规范性编码还可以让开发职员养成好的编码习惯,甚至锻炼出更加严谨的思维: 02 命名规范 1. 一般概念 尽量使用完整的英文描述符 采用适用于相关领域