目录

• 介绍
  • 标准化的重要性
  • 解释
  • 认同观点
  • 项目的四个阶段
• 命名规则
  • 合适的命名
  • 缩写词不要全部使用大写字母
  • 类命名
  • 类库命名
  • 方法命名
  • 类属性命名
  • 方法中参数命名
  • 变量命名
  • 引用变量和函数返回引用
  • 全局变量
  • 定义命名 / 全局常量
  • 静态变量
  • 函数命名
  • php文件扩展名
• 文档规则
  • 评价注释
  • Comments Should Tell a Story
  • Document Decisions
  • 使用标头说明
  • Make Gotchas Explicit
  • Interface and Implementation Documentation
  • 目录文档
• 复杂性管理规则
  • Layering
  • Open/Closed Principle
  • Design by Contract
• 类规则
  • Different Accessor Styles
  • 别在对象架构期做实际的工作
  • Thin vs. Fat Class Interfaces
  • 短方法
• 进程规则
  • Use a Design Notation and Process
  • Using Use Cases
  • Code Reviews
  • Create a Source Code Control System Early and Not Often
  • Create a Bug Tracking System Early and Not Often
  • RCS关键词、更改记录和历史记录规则
  • Honor Responsibilities
• 格式化
  • 大括号 {} 规则
  • 缩进/制表符/空格 规则
  • 小括号、关键词和函数 规则
  • If Then Else 格式
  • switch 格式
  • continue,break 和 ? 的使用
  • 每行一个语句
  • 声明块的定位
• 流行神话
  • Promise of OO
• 杂项
  • 不要不可思议的数字
  • 错误返回检测规则
  • 不要采用缺省值测试非零值
  • 布尔逻辑类型
  • 通常避免嵌入式的赋值
  • 重用您和其他人的艰苦工作
  • 使用if (0)来注释外部代码块
  • 其他杂项

介绍

标准化的重要性

优点

• 程序员可以了解任何代码，弄清程序的状况
• 新人可以很快的适应环境
• 防止新接触php的人出于节省时间的需要，自创一套风格并养成终生的习惯
• 防止新接触php的人一次次的犯同样的错误
• 在一致的环境下，人们可以减少犯错的机会
• 程序员们有了一致的敌人 :-)

缺点

• 因为标准由一些不懂得php的人所制定，所以标准通常看上去很傻
• 因为标准跟我做的不一样，所以标准通常看上去很傻
• 标准降低了创造力
• 标准在长期互相合作的人群中是没有必要的
• 标准强迫太多的格式
• 总之人们忽视标准

讨论

许多项目的经验能得出这样的结论：采用编程标准可以使项目更加顺利地完成。标准是成功的关
键么？当然不。但它们可以帮助我们，而且我们需要我们能得到的所有的帮助！老实说，对一个
细节标准的大部分争论主要是源自自负思想。对一个合理的标准的很少决定能被说为是缺乏技术
性的话，那只是口味的原因罢了。所以，要灵活的控制自负思想，记住，任何项目都取决于团队
合作的努力。

解释

惯例

使用“应该”一词的作用是指导项目定制项目细节规范。因为项目必须适当的包括 (include），
排除(exclude)或定制（tailor）需求。

使用“可以”一词的作用与“应该”类似，因为它指明了可选的需求。

标准实施

认同观点

1. 这行不通；
2. 也许可行吧，但是它既不实用又无聊；
3. 这是真的，而且我也告诉过你啊；
4. 这个是我先想到的；
5. 本来就应该这样。

项目的四个阶段

1. 数据库结构
2. 设计
3. 数据层
4. HTML层
   

命名规则

合适的命名

命名是程序规划的核心。古人相信只要知道一个人真正的名字就会获得凌驾于那个人之上的不可思议的力
量。只要你给事物想到正确的名字，就会给你以及后来的人带来比代码更强的力量。别笑！

名字就是事物在它所处的生态环境中一个长久而深远的结果。总的来说，只有了解系统的程序员才能为系
统取出最合适的名字。如果所有的命名都与其自然相适合，则关系清晰，含义可以推导得出，一般人的推
想也能在意料之中。

如果你发觉你的命名只有少量能和其对应事物相匹配的话， 最好还是重新好好再看看你的设计吧。

类命名

• 在为类（class ）命名前首先要知道它是什么。如果通过类名的提供的线索，你还是想不起这个类是
  什么 的话，那么你的设计就还做的不够好。
  
  
• 超过三个词组成的混合名是容易造成系统各个实体间的混淆，再看看你的设计，尝试使用（CRC Se-
  ssion card)看看该命名所对应的实体是否有着那么多的功用。
  
  
• 对于派生类的命名应该避免带其父类名的诱惑，一个类的名字只与它自身有关，和它的父类叫什么无
  关。
  
  
• 有时后缀名是有用的，例如：如果你的系统使用了代理（agent ），那么就把某个部件命名为“下
  载代理”（DownloadAgent）用以真正的传送信息。

方法和函数命名

• 通常每个方法和函数都是执行一个动作的，所以对它们的命名应该清楚的说明它们是做什么的：用
  CheckForErrors()代替ErrorCheck()，用DumpDataToFile()代替DataFile()。这么做也可以使功能和
  数据成为更可区分的物体。
  
  
• 有时后缀名是有用的:
  • Max - 含义为某实体所能赋予的最大值。
  • Cnt - 一个运行中的计数变量的当前值。
  • Key - 键值。

  例如：RetryMax 表示最多重试次数，RetryCnt 表示当前重试次数。

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

  例如：IsHitRetryLimit。

缩写词不要全部使用大写字母

• 无论如何，当遇到以下情况，你可以用首字母大写其余字母小写来代替全部使用大写字母的方法来表
  示缩写词。
  
  使用: GetHtmlStatistic.
  不使用: GetHTMLStatistic.
  

理由

• 当命名含有缩略词时，人们似乎有着非常不同的直觉。统一规定是最好，这样一来，命名的含义就完
  全可以预知了。

  举个NetworkABCKey的例子，注意C是应该是ABC里面的C还是key里面的C，这个是很令人费解的。有些
  人不在意这些，其他人却很讨厌这样。所以你会在不同的代码里看到不同的规则，使得你不知道怎么
  去叫它。

例如

 class FluidOz    // 不要写成 FluidOZ 
 class GetHtmlStatistic  // 不要写成 GetHTMLStatistic 

类命名

• 使用大写字母作为词的分隔，其他的字母均使用小写
• 名字的首字母使用大写
• 不要使用下划线('_')

理由

• 根据很多的命名方式，大部分人认为这样是最好的方式。

例如

 class NameOneTwo 

 class Name 

类库命名

• 目前命名空间正在越来越广泛的被采用，以避免不同厂商和团体类库间的类名冲突。
  
  
• 当尚未采用命名空间的时候，为了避免类名冲突，一般的做法是在类名前加上独特的前缀，两个字符就
  可以了，当然多用一些会更好。

例如

 class JjLinkList 
 { 
 } 

方法命名

• 采用与类命名一致的规则

理由

• 使用所有不同规则的大部分人发现这是最好的折衷办法。

例如

 class NameOneTwo 
 { 
  function DoIt() {}; 
  function HandleError() {}; 
 } 

类属性命名

• 属性命名应该以字符‘m'为前缀。
• 前缀‘m'后采用于类命名一致的规则。
• ‘m'总是在名字的开头起修饰作用，就像以‘r'开头表示引用一样。

理由

• 前缀'm'防止类属性和方法名发生任何冲突。你的方法名和属性名经常会很类似，特别是存取元素。

例如

 class NameOneTwo 
 { 
  function VarAbc() {}; 
  function ErrorNumber() {}; 

  var mVarAbc; 
  var mErrorNumber; 
  var mrName; 
 } 

方法中参数命名

• 第一个字符使用小写字母。
• 在首字符后的所有字都按照类命名规则首字符大写。

理由

• 你可以随时知道那个变量对应那个变量。
• 你可以使用与类名相似的名称而不至于产生重名冲突。

例如

 class NameOneTwo 
 { 
  function StartYourEngines( 
    &$rSomeEngine, 
    &$rAnotherEngine); 
 } 

变量命名

• 所有字母都使用小写
• 使用'_'作为每个词的分界。

理由

• 通过这一途径，代码中变量的作用域是清晰的。
• 所有的变量在代码中都看起来不同，容易辨认。

例如

function HandleError($errorNumber) 
{ 
  $error = OsErr(); 
  $time_of_error = OsErr->getTimeOfError; 
  $error_processor = OsErr->getErrorProcessor; 
} 

引用变量和函数返回引用

• 引用必须带‘r'前缀

理由

• 使得类型不同的变量容易辨认
• 它可以确定哪个方法返回可更改对象，哪个方法返回不可更改对象。

例如

 class Test 
 { 
  var mrStatus; 

  function DoSomething(&$rStatus) {}; 
  function &rStatus() {}; 
 } 

全局变量

• 全局变量应该带前缀‘g'。

理由

• 知道一个变量的作用域是非常重要的。

例如

 global $gLog; 
 global &$grLog; 

定义命名 / 全局常量

• 全局常量用'_'分隔每个单词。

理由

例如

define("A_GLOBAL_CONSTANT", "Hello world!"); 

静态变量

• 静态变量应该带前缀‘s'。

理由

• 知道一个变量的作用域是非常重要的。

例如

function test()
{
 static $msStatus = 0; 
} 

函数命名

• 函数名字采用C GNU的惯例，所有的字母使用小写字母，使用'_'分割单词。

理由

• 这样可以更易于区分相关联的类名。

例如

function some_bloody_function() 
{ 
} 

错误返回检测规则

• 检查所有的系统调用的错误信息，除非你要忽略错误。
• 为每条系统错误消息定义好系统错误文本以便include。

大括号 {} 规则

• 将大括号放置在关键词下方的同列处：

   if ($condition)  while ($condition) 
   {      { 
    ...     ... 
   }      } 
  

• 传统的UNIX的括号规则是，首括号与关键词同行，尾括号与关键字同列：

   if ($condition) {  while ($condition) { 
    ...     ... 
   }      } 
  

理由

• 引起剧烈争论的非原则的问题可通过折衷的办法解决，两种方法任意一种都是可以接受的，然而对于大
  多数人来说更喜欢第一种。原因就是心理研究学习范畴的东西了。

  对于更喜欢第一种还有着更多的原因。如果您使用的字符编辑器支持括号匹配功能的话（例如vi），最
  重要的就是有一个好的样式。为什么？我们说当你有一大块的程序而且想知道这一大块程序是在哪儿结
  束的话。你先移到开始的括号，按下按钮编辑器就会找到与之对应的结束括号，例如：

    if ($very_long_condition && $second_very_long_condition) 
    { 
    ... 
    } 
    else if (...) 
    { 
   ... 
    } 
  

  从一个程序块移动到另一个程序块只需要用光标和你的括号匹配键就可以了，不需要来回的移动到行末去
  找匹配的括号。

缩进/制表符/空格 规则

• 使用制表符缩进。
• 使用三到四个空格为每层次缩进。
• 不再使用只要一有需要就缩排的方法。对与最大缩进层数，并没有一个固定的规矩，假如缩进层数大于四或
  者五层的时候，你可以考虑着将代码因数分解(factoring out code)。

理由

• 许多编程者支持制表符。
• Tabs was invented for a rason
• 当人们使用差异太大的制表符标准的话，会使阅读代码变得很费力。
• 如此多的人愿意限定最大的缩进层数，它通常从未被看作是一件工作。我们相信程序员们会明智的选择嵌套
  的深度。

例如

 function func() 
 { 
  if (something bad) 
  { 
   if (another thing bad) 
   { 
   while (more input) 
   { 
   } 
   } 
  } 
 } 

小括号、关键词和函数 规则

• 不要把小括号和关键词紧贴在一起，要用空格隔开它们。
• 不要把小括号和函数名紧贴在一起。
• 除非必要，不要在Return返回语句中使用小括号。

理由

• 关键字不是函数。如果小括号紧贴着函数名和关键字，二者很容易被看成是一体的。

例如

 if (condition) 
 { 
 } 

 while (condition) 
 { 
 } 

 strcmp($s, $s1); 

 return 1; 

RCS关键词、更改记录和历史记录规则

• 别在文件以内使用 RCS 关键词。
• 别在文件中保存历史修改记录。
• 别在文件中保存作者信息记录。

理由

• The reasoning is your source control system already keeps all this information. There is no reason to clutter up source files with duplicate information that:
  • makes the files larger
  • makes doing diffs difficult as non source code lines change
  • makes the entry into the file dozens of lines lower in the file which makes a search or jump necessary for each file
  • is easily available from the source code control system and does not need embedding in the file
• When files must be sent to other organizations the comments may contain internal details that should not be exposed to outsiders.

别在对象架构期做实际的工作

当完成对象架构时，为该对象建立一个Open()方法，Open()方法应该以对象实体命名。

理由

• 构造不能返回错误 。

例如

 class Device 
 { 
  function Device() { /* initialize and other stuff */ } 
  function Open() { return FAIL; } 
 }; 

 $dev = new Device; 
 if (FAIL == $dev->Open()) exit(1); 

If Then Else 格式

布局

这由程序员决定。不同的花括号样式会产生些微不同的样观。一个通用方式是：

 if (条件1)     // 注释 
 { 
 } 
 else if (条件2)   // 注释 
 { 
 } 
 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有两个主要的问题：

• 它可以绕过测试条件。
• 它可以绕过等/不等表达式。

看看下面的例子，考虑一下问题都在哪儿发生：

while (TRUE) 
{ 
 ... 
 // A lot of code 
 ... 
 if (/* some condition */) { 
  continue; 
 } 
 ... 
 // A lot of code 
 ... 
 if ( $i++ > STOP_VALUE) break; 
} 

通过以上的例子，我们可以得出更进一步的规则：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 未完善的优化）。

记录所有的空语句

 
 while ($dest++ = $src++) 
  ;   // VOID 

不要采用缺省方法测试非零值

 
 if (FAIL != f()) 

 
 if (f()) 

非零测试采用基于缺省值的做法，那么其他函数或表达式就会受到以下的限制:

• 只能返回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

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.

评价注释

注释应该是讲述一个故事

Document Decisions

使用标头说明

利用类似ccdoc的文档抽取系统。在这一文档的其他部分描述的是怎么利用ccdoc记录一个类和方法。
这些标头说明可以以这样的一个方式来提取并分析和加以组织，它们不像一般的标头一样是无用的。
因此花时间去填上他吧。

注释布局

工程的每部分都有特定的注释布局。

Make Gotchas Explicit

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

Interface and Implementation Documentation

• Class Users
• Class Implementors

Class Users

Class Implementors

目录文档

• 该目录的功能及其包含内容
• 一个对每一文件的在线说明（带有link），每一个说明通常还应该提取文件标头的一些属性名字。
• 包括设置、使用说明
• 指导人民如何连接相关资源：
  • 源文件索引
  • 在线文档
  • 纸文档
  • 设计文档
• 其他对读者有帮助的东西

Use a Design Notation and Process

Any project brings together people of widely varying skills, knowledge, and experience. Even if everyone on a project is a genius you will still fail because people will endlessly talk past each other because there is no common language and processes binding the project together. All you'll get is massive fights, burnout, and little progress. If you send your group to training they may not come back seasoned experts but at least your group will all be on the same page; a team.

There are many popular methodologies out there. The point is to do some research, pick a method, train your people on it, and use it. Take a look at the top of this page for links to various methodologies.

You may find the CRC (class responsibility cards) approach to teasing out a design useful. Many others have. It is an informal approach encouraging team cooperation and focusing on objects doing things rather than objects having attributes. There's even a whole book on it: Using CRC Cards by Nancy M. Wilkinson.

Using Use Cases

An individual use case may have a name (although it is typically not a simple name). Its meaning is often written as an informal text description of the external actors and the sequences of events between objects that make up the transaction. Use cases can include other use cases as part of their behaviour.

Requirements Capture

Have as many use cases as needed to describe what a system needs to accomplish.

The Process

• Start by understanding the system you are trying to build.
• Create a set of use cases describing how the system is to be used by all its different audiences.
• Create a class and object model for the system.
• Run through all the use cases to make sure your model can handle all the cases. Update your model and create new use cases as necessary.

Open/Closed Principle

• open means a class has the ability to be extended.
• closed means a class is closed for modifications other than extension. The idea is once a class has been approved for use having gone through code reviews, unit tests, and other qualifying procedures, you don't want to change the class very much, just extend it.

In practice the Open/Closed principle simply means making good use of our old friends abstraction and polymorphism. Abstraction to factor out common processes and ideas. Inheritance to create an interface that must be adhered to by derived classes.

Design by Contract

The contract is enforced in languages like Eiffel by pre and post condition statements that are actually part of the language. In other languages a bit of faith is needed.

Design by contract when coupled with language based verification mechanisms is a very powerful idea. It makes programming more like assembling spec'd parts.

其他杂项

• 在需要用到离散的数值使，不要使用浮点数变量。采用浮点数来做循环计数器无异于向自己的脚
  开枪。测试浮点数时总要使用 <= 或 => ，永远不要用 = 或 => 。

• 不要使用程序自动美化器，得益于好的程序样式的主要的人就是程序员自己，特别是刚开着手代
  码、算法设计的程序员，使用程序自动美化器仅仅能根据语法来更正程序，因此当对空白和缩进
  的注意有很大需要时，它是不可能做到的。正常的细心注意细节的程序员们能很好的用清晰直观
  的样式来完成一个函数或文件（换句话来说，一些直观的样式是意向的规定而不是程序自动美化
  器能读懂的智慧）。马虎的程序员应该学习细致的程序员，不要依赖程序自动美化器来增加程序
  的可读性。最初的美化器是必须分析源代码的程序，复杂的美化器不值得通过这样获得好处，美
  化器最好用于生成总的机器建立（machine-generated）格式代码。

• 对逻辑表达式第二个 = 不小心的忽略是一个问题，以下显得混乱而且更像是错误：

    if ($abool= $bbool) { ... } 
    

  程序员在这里真的是要赋值么？一般常常是，但通常又不是这样。这样避免引起这样的混乱呢？解
  决方案就是不要这样做，利用显式和隐式的判断测试，推荐的方法是在做测试前先做赋值：

   
    $abool= $bbool; 
    if ($abool) { ... } 
   

使用if (0)来注释外部代码块

 function example() 
 { 
  great looking code 

  if (0) { 
  lots of code 
  } 

  more code 
 } 

你不能使用/**/，因为注释内部不能包含注释，而大段的程序中可以包含注释，不是么？

Different Accessor Styles

Why Accessors?

To see why ask yourself:

• What if the object decided to provide the attribute in a way other than physical containment?
• What if it had to do a database lookup for the attribute?
• What if a different object now contained the attribute?

Implementing Accessors

Get/Set

 class X 
 { 
  function GetAge()  { return $this->mAge; } 
  function SetAge($age) { $mAge= $age; } 
  var $mAge; 
 } 

One Method Name

 class X 
 { 
  function Age()   { return $mAge; } 
  function Age($age)  { $mAge= $age; } 
  var $mAge; 
 } 

Attributes as Objects

 class X 
 { 
  function Age()   { return $mAge; } 
  function rAge()   { return &$mAge; } 

  function Name()   { return mName; } 
  function rName()   { return &$mName; } 

  var $mAge; 
  var $mName; 
 }
 
 X $x; 
 $x->rName()= "test"; 

When using rAge(), which is not a real object, the variable is set directly because rAge() returns a reference. The object can do no checking of the value or do any representation reformatting. For many simple attributes, however, these are not horrible restrictions.

Layering

A layering violation simply means we have dependency between layers that is not controlled by a well defined interface. When one of the layers changes code could break. We don't want code to break so we want layers to work only with other adjacent layers.

Sometimes we need to jump layers for performance reasons. This is fine, but we should know we are doing it and document appropriately.

Code Reviews

My god he's questioning code reviews, he's not an engineer!

Not really, it's the form of code reviews and how they fit into normally late chaotic projects is what is being questioned.

First, code reviews are way too late to do much of anything useful. What needs reviewing are requirements and design. This is where you will get more bang for the buck.

Get all relevant people in a room. Lock them in. Go over the class design and requirements until the former is good and the latter is being met. Having all the relevant people in the room makes this process a deep fruitful one as questions can be immediately answered and issues immediately explored. Usually only a couple of such meetings are necessary.

If the above process is done well coding will take care of itself. If you find problems in the code review the best you can usually do is a rewrite after someone has sunk a ton of time and effort into making the code "work."

You will still want to do a code review, just do it offline. Have a couple people you trust read the code in question and simply make comments to the programmer. Then the programmer and reviewers can discuss issues and work them out. Email and quick pointed discussions work well. This approach meets the goals and doesn't take the time of 6 people to do it.

Create a Source Code Control System Early and Not Often

Some issues to keep in mind:

• Shared source environments like CVS usually work best in largish projects.
• If you use CVS use a reference tree approach. With this approach a master build tree is kept of various builds. Programmers checkout source against the build they are working on. They only checkout what they need because the make system uses the build for anything not found locally. Using the -I and -L flags makes this system easy to setup. Search locally for any files and libraries then search in the reference build. This approach saves on disk space and build time.
• Get a lot of disk space. With disk space as cheap it is there is no reason not to keep plenty of builds around.
• Make simple things simple. It should be dead simple and well documented on how to:
  • check out modules to build
  • how to change files
  • how to add new modules into the system
  • how to delete modules and files
  • how to check in changes
  • what are the available libraries and include files
  • how to get the build environment including all compilers and other tools

  Make a web page or document or whatever. New programmers shouldn't have to go around begging for build secrets from the old timers.

• On checkins log comments should be useful. These comments should be collected every night and sent to interested parties.

Sources

Create a Bug Tracking System Early and Not Often

Programmers generally resist bug tracking, yet when used correctly it can really help a project:

• Problems aren't dropped on the floor.
• Problems are automatically routed to responsible individuals.
• The lifecycle of a problem is tracked so people can argue back and forth with good information.
• Managers can make the big schedule and staffing decisions based on the number of and types of bugs in the system.
• Configuration management has a hope of matching patches back to the problems they fix.
• QA and technical support have a communication medium with developers.

FYI, it's not a good idea to reward people by the number of bugs they fix :-)

Source code control should be linked to the bug tracking system. During the part of a project where source is frozen before a release only checkins accompanied by a valid bug ID should be accepted. And when code is changed to fix a bug the bug ID should be included in the checkin comments.

Sources

Honor Responsibilities

Face it, if you don't own a piece of code you can't possibly be in a position to change it. There's too much context. Assumptions seemingly reasonable to you may be totally wrong. If you need a change simply ask the responsible person to change it. Or ask them if it is OK to make such-n-such a change. If they say OK then go ahead, otherwise holster your editor.

Every rule has exceptions. If it's 3 in the morning and you need to make a change to make a deliverable then you have to do it. If someone is on vacation and no one has been assigned their module then you have to do it. If you make changes in other people's code try and use the same style they have adopted.

Programmers need to mark with comments code that is particularly sensitive to change. If code in one area requires changes to code in an another area then say so. If changing data formats will cause conflicts with persistent stores or remote message sending then say so. If you are trying to minimize memory usage or achieve some other end then say so. Not everyone is as brilliant as you.

The worst sin is to flit through the system changing bits of code to match your coding style. If someone isn't coding to the standards then ask them or ask your manager to ask them to code to the standards. Use common courtesy.

Code with common responsibility should be treated with care. Resist making radical changes as the conflicts will be hard to resolve. Put comments in the file on how the file should be extended so everyone will follow the same rules. Try and use a common structure in all common files so people don't have to guess on where to find things and how to make changes. Checkin changes as soon as possible so conflicts don't build up.

As an aside, module responsibilities must also be assigned for bug tracking purposes.

PHP文件扩展名

• 所有浏览者可见页面使用.html
• 所有类、函数库文件使用.php

理由

• 扩展名描述的是那种数据是用户将会收到的。PHP是解释为HTML的。

不要不可思议的数字

if  (22 == $foo) { start_thermo_nuclear_war(); } 
else if (19 == $foo) { refund_lotso_money(); } 
else if (16 == $foo) { infinite_loop(); } 
else    { cry_cause_im_lost(); } 

使用不可思议的数字是该程序员是业余运动员的重要标志，这样的程序员从来没有在团队环境中工作过，
又或者是为了维持代码而不得不做的，否则他们永远不会做这样的事。

你应该用define()来给你想表示某样东西的数值一个真正的名字，而不是采用赤裸裸的数字，例如：

define("PRESIDENT_WENT_CRAZY", "22"); 
define("WE_GOOFED", "19"); 
define("THEY_DIDNT_PAY", "16"); 

if  (PRESIDENT_WENT_CRAZY == $foo) { start_thermo_nuclear_war(); } 
else if (WE_GOOFED   == $foo) { refund_lotso_money(); } 
else if (THEY_DIDNT_PAY  == $foo) { infinite_loop(); } 
else         { happy_days_i_know_why_im_here(); } 

Promise of OO

Robert Martin put OO in perspective:

• OO, when properly employed, does enhance the reusability of software. But it does so at the cost of complexity and design time. Reusable code is more complex and takes longer to design and implement. Furthermore, it often takes two or more tries to create something that is even marginally reusable.
• OO, when properly employed, does enhance the software's resilience to change. But it does so at the cost of complexity and design time. This trade off is almost always a win, but it is hard to swallow sometimes.
• OO does not necessarily make anything easier to understand. There is no magical mapping between the software concepts and every human's map of the real world. Every person is different. What one person percieves to be a simple and elegant design, another will perceive as convoluted and opaque.
• If a team has been able, by applying point 1 above, to create a repository of reusable items, then development times can begin to shrink significantly due to reuse.
• If a team has been able, by applying point 2 above, to create software that is resilient to change, then maintenance of that software will be much simpler and much less error prone.

Thin vs. Fat Class Interfaces

The two extremes are thin classes versus thick classes. Thin classes are minimalist classes. Thin classes have as few methods as possible. The expectation is users will derive their own class from the thin class adding any needed methods.

While thin classes may seem "clean" they really aren't. You can't do much with a thin class. Its main purpose is setting up a type. Since thin classes have so little functionality many programmers in a project will create derived classes with everyone adding basically the same methods. This leads to code duplication and maintenance problems which is part of the reason we use objects in the first place. The obvious solution is to push methods up to the base class. Push enough methods up to the base class and you get thick classes.

Thick classes have a lot of methods. If you can think of it a thick class will have it. Why is this a problem? It may not be. If the methods are directly related to the class then there's no real problem with the class containing them. The problem is people get lazy and start adding methods to a class that are related to the class in some willow wispy way, but would be better factored out into another class. Judgment comes into play again.

Thick classes have other problems. As classes get larger they may become harder to understand. They also become harder to debug as interactions become less predictable. And when a method is changed that you don't use or care about your code will still have to be retested, and rereleased.

Recent Changes

1. 2000-11-16. Release