/*
* @(#)Cngift.php 1.82 03/06/25
*
* 开花石头编写的示例文档
* 将对编码规范做简单的示范
*
*/
require( “db.php” );

/**
* 示范用类
*
* @version 1.82 03.06.25
* @author 开花石头
*/
class Blah extends SomeClass {
/* 这个类运行时的注释写在这里 */

/** 关于变量的注释写在这里 */
static int $classVar1;

/**
* 对变量编写的多行注释写在这里
*/
static string classVar2;

/** 变量的文档注释 */
int instanceVar1;

/** 变量的文档注释 */
int[] instanceVar3;

/**
* 构造函数的注释
*/
function Blah() {
// …在这里执行…
}

/**
* …函数的文档注释…
*/
function doSomething() {
// …在这里执行…
}

/**
* …方法的注释文档..
* 多行注释
*/
public void doSomethingElse(Object someParam) {
// …在这里执行…
}
}

在三种主要的大括号放置规则中，有两种是可以接受的，如下的第一种是最好的：
将大括号放置在关键词下方的同列处：
if (condition)
{
…

while (condition)
{
…
}
}
传统的UNIX的括号规则是，首括号与关键词同行，尾括号与关键字同列：
if (condition) {

…

while (condition) {

…

}
}
引起剧烈争论的非原则的问题可通过折衷的办法解决，两种方法任意一种都是可以接受的，然而对于大多数人来说更喜欢第一种。原因就是心理研究学习范畴的东西了。
对于更喜欢第一种还有着更多的原因。如果您使用的字符编辑器支持括号匹配功能的话（例如vi），最重要的就是有一个好的样式。为什么？我们说当你有一大块的程序而且想知道这一大块程序是在哪儿结束的话。你先移到开始的括号，按下按钮编辑器就会找到与之对应的结束括号，例如：

if (veryLongCondition && secondVeryLongCondition)
{
…
}
else if (…)
{
…
}
从一个程序块移动到另一个程序块只需要用光标和你的括号匹配键就可以了，不需找匹配的括号。

如果一个包含二元运算符的表达式出现在三元运算符” ? : “的”?”之前，那么应该给表达式添上一对圆括号。例如：
(x >= 0) ? x : -x;

设法让你的程序结构符合目的。例如：
if (booleanExpression) {
return true;
} else {
return false;
}

应该代之以如下方法：
return booleanExpression;

类似地：
if (condition) {
return x;
}
return y;

应该写做：
return (condition ? x : y);

一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。你不能假设别的程序员和你一样清楚运算符的优先级。
if ($a == $b && $c == $d) // 错误
if (($a == $b) && ($c == $d)) // 正确

一个唯一命名空间的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org，或1981年ISO 3166标准所指定的标识国家的英文双字符代码。命名空间的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部门(department)，项目(project)，机器(machine)，或注册名(login names)，也可以按功能模块来分类。

类属性的命名

属性命名应该以字符‘m’为前缀。
前缀‘m’后采用于类命名一致的规则。
‘m’总是在名字的开头起修饰作用，就像以‘r’开头表示引用一样。
理由
前缀’m'防止类属性和方法名发生任何冲突。你的方法名和属性名经常会很类似，特别是存取元素。
例如
class NameOneTwo
{
int $mVarAbc;
int $mErrorNumber;
String $mrName;
}

除了变量名外，所有实例，包括类，类常量，均采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。
变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。

char $c;
int $i;
float $myWidth;

变量赋值

避免在一个语句中给多个变量赋相同的值。它很难读懂。例如：
$fooBar.fChar = $barFoo.lchar = ‘c’; // 错误

不要将赋值运算符用在容易与相等关系运算符混淆的地方。例如：
if ($c++ = $d++) { // 错误
…
}

应该写成
if (($c++ = $d++) != 0) {
…
}

不要使用内嵌(embedded)赋值运算符试图提高运行时的效率，这是编译器的工作。例如：
$d = ($a = $b + $c) + $r; // 错误

应该写成
$a = $b + $c;
$d = $a + $r;

实例变量

大小写规则和变量名相似，除了前面需要一个下划线

int $_employeeId;
String $_name;
Customer $_customer;
常量

类常量和ANSI常量的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误)

static final int $MIN_WIDTH = 4;
static final int $MAX_WIDTH = 999;
static final int $GET_THE_CPU = 1;

位于for循环中作为计数器值的数字常量，除了-1,0和1之外，不应被直接写入代码。

下列情况应该使用空格：
- 一个紧跟着括号的关键字应该被空格分开，例如：
while ( true ) {
…
}

注意：空格不应该置于方法名与其左括号之间。这将有助于区分关键字和方法调用。
- 空白应该位于参数列表中逗号的后面
- 所有的二元运算符，除了”.”，应该使用空格将之与操作数分开。一元操作符和操作数之间不因该加空格，比如：负号(“-”)、自增(“++”)和自减(“–”)。例如：
$a += $c + $d;
$a = ( $a + $b ) / ( $c * $d );

while ( $d++ = $s++ ) {
$n++;
}
printSize( “size is ” + $foo + “\n” );

- for语句中的表达式应该被空格分开，例如：
for (expr1; expr2; expr3)

- 强制转型后应该跟一个空格，例如：
myMethod( (byte) $aNum, (int) $x );
myMethod( (int) ($cp + 5 ), ( (int) ($i + 3)) + 1 );

方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。
function run();
function runFast();
function getBackground();

通常每个方法都是执行一个动作的，所以对它的命名应该清楚的说明它是做什么的：用checkForErrors()代替errorCheck()，用dumpDataToFile()代替dataFile()。这么做也可以使功能和数据成为更可区分的物体。

有时后缀名是有用的:
Max – 含义为某实体所能赋予的最大值。
Cnt – 一个运行中的计数变量的当前值。
Key – 键值。
例如：retryMax 表示最多重试次数，retryCnt 表示当前重试次数。

有时前缀名是有用的：
is – 含义为问一个关于某样事物的问题。无论何时，当人们看到Is就会知道这是一个问题。
get – 含义为取得一个数值。
set – 含义为设定一个数值
例如：isHitRetryLimit

空行将逻辑相关的代码段分隔开，以提高可读性。

下列情况应该总是使用两个空行：
- 一个源文件的两个片段(section)之间
- 类声明声明之间

下列情况应该总是使用一个空行：
- 两个方法之间
- 方法内的局部变量和方法的第一条语句之间
- 块注释或单行注释之前
- 一个方法内的两个逻辑段之间，用以提高可读性

尽量在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。

布局

只在代码块的开始处声明变量。（一个块是指任何被包含在大括号”{“和”}”中间的代码。）不要在首次用到该变量时才声明之。这会把注意力不集中的程序员搞糊涂，同时会妨碍代码在该作用域内的可移植性。
function myMethod() {
　　int $int1 = 0; // 方法块的开始

　　if ($condition) {
　　　　int $int2 = 0; // “if”块的开始
　　　　…
　　}
}

该规则的一个例外是for循环的索引变量
for (int $i = 0; i < $maxLoops; $i++) { … }

避免声明的局部变量覆盖上一级声明的变量。例如，不要在内部代码块中声明相同的变量名：
int $count;
…
function myMethod() {
　　if ($condition) {
　　　　int $count = 0; // 避免这种声明
　　　　…
　　}
　…
}

一个switch语句应该具有如下格式：

switch (condition) {
　　case ABC:
　　/* falls through */
　　　　statements;

　　case DEF:
　　　statements;
　　　break;

　　case XYZ:
　　　　statements;
　　　　break;

　　default:
　　　　statements;
　　　　break;
}

每当一个case顺着往下执行时(因为没有break语句)，通常应在break语句的位置添加注释。上面的示例代码中就包含注释/* falls through */。

一个for语句应该具有如下格式：
for (initialization; condition; update) {
　　statements;
}

一个空的for语句(所有工作都在初始化，条件判断，更新子句中完成）应该具有如下格式：
for (initialization; condition; update);

当在for语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。若需要，可以在for循环之前(为初始化子句)或for循环末尾(为更新子句)使用单独的语句。

while语句

一个while语句应该具有如下格式
while (condition) {
　　statements;
}

一个空的while语句应该具有如下格式：
while (condition);
do…while语句

一个do-while语句应该具有如下格式：

do {
　　statements;
} while (condition);

一个try-catch语句应该具有如下格式：
try {
　　statements;
} catch (ExceptionClass e) {
　　statements;
}

一个try-catch语句后面也可能跟着一个finally语句，不论try代码块是否顺利执行完，它都会被执行。
try {
　　statements;
} catch (ExceptionClass e) {
　　statements;
} finally {
　　statements;
}

if-else语句应该具有如下格式：
if (condition){ /* 进行操作的条件 */
　　statements;
}

if (condition) {/*进行操作的条件. */
　　statements;
} else {/*进行操作的条件*/
　　statements;
}

if (condition) {/*进行操作的条件*/
　　statements;
} else if (condition) {/*进行操作的条件 */
　　statements;
} else{/*进行操作的条件*/
　　statements;
}

注意：if语句总是用”{“和”}”括起来，避免使用如下容易引起错误的格式：
if (condition) //避免这种写法，他忽略了“{}”
　　statement;

注释格式也可以像下面的这种方式写

if (condition) {
/*进行操作的条件*/
　　statements;
} else {
/*进行操作的条件*/
　　statements;
}

只要可以描述清楚各分支之间的关系，在哪里写注释均可

一个带返回值的return语句不使用小括号”()”，除非它们以某种方式使返回值更为显见。例如：
return;

return myDisk.size();

return ($size ? $size : $defaultSize);

复合语句

复合语句是包含在大括号中的语句序列，形如”{ 语句 }”。例如下面各段。

- 被括其中的语句应该较之复合语句缩进一个层次
- 左大括号”{“应位于复合语句起始行的行尾；右大括号”}”应另起一行并与复合语句首行对齐。
- 大括号可以被用于所有语句，包括单个语句，只要这些语句是诸如if-else或for控制结构的一部分。这样便于添加语句而无需担心由于忘了加括号而引入bug。

当编写类时，应该遵守以下格式规则：

- 在方法名与其参数列表之前的左括号”(“间不要有空格
- 左大括号”{“位于声明语句同行的末尾
- 右大括号”}”另起一行，与相应的声明语句对齐，除非是一个空语句，”}”应紧跟在”{“之后

class Sample extends Object {
　　int $ivar1;
　　int $ivar2;

function Sample(int $i, int $j) {
　　ivar$1 = $i;
　　ivar$2 = $j;
}

function emptyMethod() {}

　　…
}

- 方法与方法之间以空行分隔

推荐一行一个声明，因为这样以利于写注释。亦即，
int $level; // 缩进的程度
int $size; // 由制表符决定

要优于，

int $level, $size;

不要将不同类型变量的声明放在同一行，例如：
int $foo, $fooarray[]; //错误

注意：上面的例子中，在类型和标识符之间放了一个空格，另一种被允许的替代方式是使用制表符：
int $level; // 缩进的程度
int $size; // 由制表符决定
$currentEntry; // 通常选择制表符作为缩进的标准

所有的源文件都应该在开头有一个C语言风格的注释，其中列出类名、功能、版本信息、日期、作者和版权声明：
/*
　* 类名
　* 功能
　* 版本
　* 日期
　* 作者
　* 版权
　*/

如果对文件进行了修改，应该在文件头中说明修改目的、修改日期、修改人，并变更文件的版本信息；如果修改问文件的一部分，则在文件中进行注释即可，并且标识出修改部分的起止位置

……

/*
　* 修改目的
　* 修改日期
　* 修改人
　* 版本
　*/

……

修改起始

……

……

修改结束

……

单行注释

短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释。单行注释之前应该有一个空行。以下是一个代码中单行注释的例子：
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)。例如，有关一个类实现的细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。

文档注释不能放在一个方法或构造器的定义块中，因为程序会将位于文档注释之后的第一个声明与其相关联。