规范2

If Then Else 格式
布局
这由程序员决定。不同的花括号样式会产生些微不同的样观。一个通用方式是：
   if (条件1)                 // 注释
   {
   }
   else if (条件2)            // 注释
   {
   }
   else                           // 注释
   {
   }
如果你有用到else if 语句的话，通常最好有一个else块以用于处理未处理到的其他情况。可以的话
放一个记录信息注释在else处，即使在else没有任何的动作。
条件格式
总是将恒量放在等号/不等号的左边，例如：
if ( 6 == $errorNum ) ...
一个原因是假如你在等式中漏了一个等号，语法检查器会为你报错。第二个原因是你能立刻找到数值
而不是在你的表达式的末端找到它。需要一点时间来习惯这个格式，但是它确实很有用。
--------------------------------------------------------------------------------
switch 格式
Falling through a case statement into the next case statement shall be permitted as long as a comment is included.
default case总应该存在，它应该不被到达，然而如果到达了就会触发一个错误。
如果你要创立一个变量，那就把所有的代码放在块中。
例如
   switch (...)
   {
      case 1:
         ...
      // FALL THROUGH
      case 2:
      {
         $v = get_week_number();
         ...
      }
      break;
      default:
   }
--------------------------------------------------------------------------------
continue,break 和 ? 的使用:
Continue 和 Break
Continue 和 break 其实是变相的隐蔽的 goto方法。
Continue 和 break 像 goto 一样，它们在代码中是有魔力的，所以要节俭（尽可能少）的使用它们。
使用了这一简单的魔法，由于一些未公开的原因，读者将会被定向到只有上帝才知道的地方去。
Continue有两个主要的问题：
它可以绕过测试条件。
它可以绕过等/不等表达式。
看看下面的例子，考虑一下问题都在哪儿发生：
while (TRUE)
{
   ...
   // A lot of code
   ...
   if (/* some condition */) {
      continue;
   }
   ...
   // A lot of code
   ...
   if ( $i++ > STOP_VALUE) break;
}
注意："A lot of code"是必须的，这是为了让程序员们不能那么容易的找出错误。
通过以上的例子，我们可以得出更进一步的规则：continue 和 break 混合使用是引起灾难的正确方法。
?:
麻烦在于人民往往试着在 ? 和 : 之间塞满了许多的代码。以下的是一些清晰的连接规则：
把条件放在括号内以使它和其他的代码相分离。
如果可能的话，动作可以用简单的函数。
把所做的动作，“?”，“:”放在不同的行，除非他们可以清楚的放在同一行。
例如
   (condition) ? funct1() : func2();
   or
   (condition)
      ? long statement
      : another long statement;
--------------------------------------------------------------------------------
声明块的定位
声明代码块需要对齐。
理由Justification
清晰。
变量初始化的类似代码块应该列表。
The ??token should be adjacent to the type, not the name.
例如
   var       $mDate
   var&      $mrDate
   var&      $mrName
   var       $mName
   $mDate    = 0;
   $mrDate   = NULL;
   $mrName   = 0;
   $mName    = NULL;
--------------------------------------------------------------------------------
每行一个语句
除非这些语句有很密切的联系，否则每行只写一个语句。
--------------------------------------------------------------------------------
短方法
方法代码要限制在一页内。
理由
这个思想是，每一个方法代表着一个完成单独目的的技术。
从长远来说，过多的无效参数是错误的。
调用函数比不调用要慢，但是这需要详细考虑做出决定（见premature optimization 未完善的优化）。
--------------------------------------------------------------------------------
记录所有的空语句
总是记录下for或者是while的空块语句，以便清楚的知道该段代码是漏掉了，还是故意不写的。
   while ($dest++ = $src++)
      ;         // VOID
--------------------------------------------------------------------------------
不要采用缺省方法测试非零值
不要采用缺省值测试非零值，也就是使用：
   if (FAIL != f())
比下面的方法好：
   if (f())
即使 FAIL 可以含有 0 值 ，也就是PHP认为false的表示。在某人决定用-1代替0作为失败返回值的时候，
一个显式的测试就可以帮助你了。就算是比较值不会变化也应该使用显式的比较；例如：if (!($bufsize % strlen($str)))
应该写成：if (($bufsize % strlen($str)) == 0)以表示测试的数值（不是布尔）型。一个经常出
问题的地方就是使用strcmp来测试一个字符等式，结果永远也不会等于缺省值。
非零测试采用基于缺省值的做法，那么其他函数或表达式就会受到以下的限制:
只能返回0表示失败，不能为/有其他的值。
命名以便让一个真(true)的返回值是绝对显然的，调用函数IsValid()而不是Checkvalid()。
--------------------------------------------------------------------------------
布尔逻辑类型
大部分函数在FALSE的时候返回0，但是发挥非0值就代表TRUE，因而不要用1（TRUE，YES，诸如此类）等式检测一个布尔值，应该用0（FALSE，NO，诸如此类）的不等式来代替：
   if (TRUE == func()) { ...
应该写成：
   if (FALSE != func()) { ...
--------------------------------------------------------------------------------
通常避免嵌入式的赋值
有时候在某些地方我们可以看到嵌入式赋值的语句，那些结构不是一个比较好的少冗余，可读性强的方法。
   while ($a != ($c = getchar()))
   {
      process the character
   }
++和--操作符类似于赋值语句。因此，出于许多的目的，在使用函数的时候会产生副作用。使用嵌入式赋值
提高运行时性能是可能的。无论怎样，程序员在使用嵌入式赋值语句时需要考虑在增长的速度和减少的可维
护性两者间加以权衡。例如：
   a = b + c;
   d = a + r;
不要写成：
   d = (a = b + c) + r;
虽然后者可以节省一个周期。但在长远来看，随着程序的维护费用渐渐增长，程序的编写者对代码渐渐遗忘，
就会减少在成熟期的最优化所得。
--------------------------------------------------------------------------------
重用您和其他人的艰苦工作
跨工程的重用在没有一个通用结构的情况下几乎是不可能的。对象符合他们现有的服务需求，不同的过程有着
不同的服务需求环境，这使对象重用变得很困难。
开发一个通用结构需要预先花费许多的努力来设计。当努力不成功的时候，无论出于什么原因，有几种办法推
荐使用：
请教！给群组发Email求助
这个简单的方法很少被使用。因为有些程序员们觉得如果他向其他人求助，会显得自己水平低，这多傻啊!做新
的有趣的工作，不要一遍又一遍的做别人已经做过的东西。
如果你需要某些事项的源代码，如果已经有某人做过的话，就向群组发email求助。结果会很惊喜哦！
在许多大的群组中，个人往往不知道其他人在干什么。你甚至可以发现某人在找一些东西做，并且自愿为你写代
码，如果人们在一起工作，外面就总有一个金矿。
告诉！当你在做事的时候，把它告诉所有人
如果你做了什么可重用的东西的话，让其他人知道。别害羞，也不要为了保护自豪感而把你的工作成果藏起来。
一旦养成共享工作成果的习惯，每个人都会获得更多。
Don't be Afraid of Small Libraries
对于代码重用，一个常见的问题就是人们不从他们做过的代码中做库。一个可重用的类可能正隐蔽在一个程序目
录并且决不会有被分享的激动，因为程序员不会把类分拆出来加入库中。
这样的其中一个原因就是人们不喜欢做一个小库，对小库有一些不正确感觉。把这样的感觉克服掉吧，电脑才不
关心你有多少个库呢。
如果你有一些代码可以重用，而且不能放入一个已经存在的库中，那么就做一个新的库吧。如果人们真的考虑重
用的话，库不会在很长的一段时间里保持那么小的。
If you are afraid of having to update makefiles when libraries are recomposed or added then don't include libraries in your makefiles, include the idea of services. Base level makefiles define services that are each composed of a set of libraries. Higher level makefiles specify the services they want. When the libraries for a service change only the lower level makefiles will have to change.
Keep a Repository
Most companies have no idea what code they have. And most programmers still don't communicate what they have done or ask for what currently exists. The solution is to keep a repository of what's available.
In an ideal world a programmer could go to a web page, browse or search a list of packaged libraries, taking what they need. If you can set up such a system where programmers voluntarily maintain such a system, great. If you have a librarian in charge of detecting reusability, even better.
Another approach is to automatically generate a repository from the source code. This is done by using common class, method, library, and subsystem headers that can double as man pages and repository entries.
--------------------------------------------------------------------------------
评价注释
注释应该是讲述一个故事
Consider your comments a story describing the system. Expect your comments to be extracted by a robot and formed into a man page. Class comments are one part of the story, method signature comments are another part of the story, method arguments another part, and method implementation yet another part. All these parts should weave together and inform someone else at another point of time just exactly what you did and why.
Document Decisions
Comments should document decisions. At every point where you had a choice of what to do place a comment describing which choice you made and why. Archeologists will find this the most useful information.
使用标头说明
利用类似clearcase/" target="_blank" >ccdoc的文档抽取系统。在这一文档的其他部分描述的是怎么利用ccdoc记录一个类和方法。
这些标头说明可以以这样的一个方式来提取并分析和加以组织，它们不像一般的标头一样是无用的。
因此花时间去填上他吧。
注释布局
工程的每部分都有特定的注释布局。
Make Gotchas Explicit
Explicitly comment variables changed out of the normal control flow or other code likely to break during maintenance. Embedded keywords are used to point out issues and potential problems. Consider a robot will parse your comments looking for keywords, stripping them out, and making a report so people can make a special effort where needed.
Gotcha Keywords
:TODO: topic
Means there's more to do here, don't forget.
:BUG: [bugid] topic
means there's a Known bug here, explain it and optionally give a bug ID.
:KLUDGE:
When you've done something ugly say so and explain how you would do it differently next time if you had more time.
:TRICKY:
Tells somebody that the following code is very tricky so don't go changing it without thinking.
:WARNING:
Beware of something.
:PHARSER:
Sometimes you need to work around a pharser problem. Document it. The problem may go away eventually.
:ATTRIBUTE: value
The general form of an attribute embedded in a comment. You can make up your own attributes and they'll be extracted.
Gotcha Formatting
Make the gotcha keyword the first symbol in the comment.
Comments may consist of multiple lines, but the first line should be a self-containing, meaningful summary.
The writer's name and the date of the remark should be part of the comment. This information is in the source repository, but it can take a quite a while to find out when and by whom it was added. Often gotchas stick around longer than they should. Embedding date information allows other programmer to make this decision. Embedding who information lets us know who to ask.
Example
   // :TODO: tmh 960810: possible performance problem
   // We should really use a hash table here but for now we'll
   // use a linear search.
   // :KLUDGE: tmh 960810: possible unsafe type cast
   // We need a cast here to recover the derived type. It should
   // probably use a virtual method or template.
See Also
See Interface and Implementation Documentation for more details on how documentation should be laid out.
--------------------------------------------------------------------------------
Interface and Implementation Documentation
There are two main audiences for documentation:
Class Users
Class Implementors
With a little forethought we can extract both types of documentation directly from source code.
Class Users
Class users need class interface information which when structured correctly can be extracted directly from a header file. When filling out the header comment blocks for a class, only include information needed by programmers who use the class. Don't delve into algorithm implementation details unless the details are needed by a user of the class. Consider comments in a header file a man page in waiting.
Class Implementors
Class implementors require in-depth knowledge of how a class is implemented. This comment type is found in the source file(s) implementing a class. Don't worry about interface issues. Header comment blocks in a source file should cover algorithm issues and other design decisions. Comment blocks within a method's implementation should explain even more.
--------------------------------------------------------------------------------

原文转自：http://www.ltesting.net