|
|
马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。
您需要 登录 才可以下载或查看，没有帐号？立即注册
x
掌握静态网页的制作技术是学习开发网站的先决条件，这一点就讲到这里，因为这篇文章不是教程文章，也就不对技术进行深入的刨析了。编程|尺度 PHP 编程尺度
最初修正日期: 2000-11-16
PHP编程尺度是经过Todd Hoff允许，基于《C++ 编程尺度》为PHP而重写的，
作者为Fredrik Kristiansen，
利用本尺度，假如您想拷贝一份留做自用的话，那是完整收费的，这也是咱们制造它的缘由。假设您发明了任何的毛病又或是有任何的改善，请您给笔者发一个email，以便笔者将它们兼并到最新更新中去。
目次
引见
尺度化的主要性
注释
认同概念
项目标四个阶段
定名划定规矩
适合的定名
缩写词不要全体利用大写字母
类定名
类库定名
办法定名
类属人命名
办法中参数定名
变量定名
援用变量和函数前往援用
全局变量
界说定名 / 全局常量
静态变量
函数定名
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）需求。
利用“可以”一词的感化与“应当”相似，由于它指了然可选的需求。
尺度实行
起首应当在开辟小组的外部找出一切的最主要的元素，或许尺度对你的情况还不敷得当。它能够已概
括了 主要的成绩，也能够还有人对个中的某些成绩暗示激烈的否决。
不管在甚么情形下，只需最初顺遂的话，人们将成熟的分明到这个尺度是公道的，然后其他的法式员们
也会发明它的公道性，并感觉带着一些保存去遵守这一尺度是值得的。
假如没有自愿的协作，可以制订需求：尺度必定要经由代码的查验。
假如没有查验的话，这个处理计划仅仅是一个创立在不准确的基本上的一大群好笑的人。
认同概念
这行欠亨；
或许可行吧，然而它既不适用又无聊；
这是真的，并且我也告知过你啊；
这个是我先想到的；
原本就应当如许。
假如您带着否认的偏见而来对待事物的话，请您坚持开放的思惟。你仍可以做出它是空话的结论，然而做
出结论的办法就是你必需要可以承受分歧的思惟。请您给本人一点工夫去做到它。
项目标四个阶段
数据库布局
设计
数据层
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
----------------------------------------------------------------------------
类库定名
今朝定名空间正在愈来愈普遍的被采取，以免分歧厂商和整体类库间的类名抵触。
当还没有采取定名空间的时分，为了不类名抵触，普通的做法是在类名前加上共同的前缀，两个字符就
可以了，固然多用一些会更好。
例如
John Johnson的数据布局类库可以用Jj做为前缀，以下：
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关头词的划定规矩必需改动，个中包含利用CVS等相似的撑持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 // 正文
{
}
假如你有效到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.
利用标头申明
使用相似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.
----------------------------------------------------------------------------
目次文档
一切的目次下都需求具有README文档，个中包含：
该目次的功效及其包括内容
一个对每文件的在线申明（带有link），每个申明凡是还应当提取文件标头的一些属性名字。
包含设置、利用申明
指点国民若何毗连相干资本：
源文件索引
在线文档
纸文档
设计文档
其他对读者有匡助的器材
思索一下，当每一个原本的工程人员走了，在6个月以内来的一个新人，谁人伶仃吃惊吓的探险者经由过程全部
工程的源代码目次树，浏览申明文件，源文件的标头申明等等做为地图，他应当有才能穿越全部工程。
----------------------------------------------------------------------------
Use a Design Notation and Process
Programmers need to have a common language for talking about coding, designs, and the software process in general. This is critical to project success.
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
A use case is a generic description of an entire transaction involving several objects. A use case can also describe the behaviour of a set of objects, such as an organization. A use case model thus presents a collection of use cases and is typically used to specify the behavior of a whole application system together with one or more external actors that interact with the system.
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
Use cases attempt to capture the requirements for a system in an understandable form. The idea is by running through a set of use case we can verify that the system is doing what it should be doing.
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
The Open/Closed principle states a class must be open and closed where:
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.
The Open/Closed principle is a pitch for stability. A system is extended by adding new code not by changing already working code. Programmers often don't feel comfortable changing old code because it works! This principle just gives you an academic sounding justification for your fears :-)
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 idea of design by contract is strongly related to LSP . A contract is a formal statement of what to expect from another party. In this case the contract is between pieces of code. An object and/or method states that it does X and you are supposed to believe it. For example, when you ask an object for its volume that's what you should get. And because volume is a verifiable attribute of a thing you could run a series of checks to verify volume is correct, that is, it satisfies its 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)来正文内部代码块
有时需求正文大段的测试代码，最复杂的办法就是利用if (0)块：
function example()
{
great looking code
if (0) {
lots of code
}
more code
}
你不克不及利用/**/，由于正文外部不克不及包括正文，而大段的法式中可以包括正文，不是么？
----------------------------------------------------------------------------
Different Accessor Styles
Why Accessors?
Access methods provide access to the physical or logical attributes of an object. We disallow direct access to attributes to break dependencies, the reason we do most things. Directly accessing an attribute exposes implementation details about the object.
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?
If any of the above changed code would break. An object makes a contract with the user to provide access to a particular attribute; it should not promise how it gets those attributes. Accessing a physical attribute makes such a promise.
Implementing Accessors
There are three major idioms for creating 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;
}
Similar to Get/Set but cleaner. Use this approach when not using the Attributes as Objects approach.
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";
The above two attribute examples shows the strength and weakness of the Attributes as Objects approach.
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
Layering is the primary technique for reducing complexity in a system. A system should be divided into layers. Layers should communicate between adjacent layers using well defined interfaces. When a layer uses a non-adjacent layer then a layering violation has occurred.
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
If you can make a formal code review work then my hat is off to you. Code reviews can be very useful. Unfortunately they often degrade into nit picking sessions and endless arguments about silly things. They also tend to take a lot of people's time for a questionable payback.
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
A common build system and source code control system should be put in place as early as possible in a project's lifecycle, preferably before anyone starts coding. Source code control is the structural glue binding a project together. If programmers can't easily use each other's products then you'll never be able to make a good reproducible build and people will piss away a lot of time. It's also hell converting rogue build environments to a standard system. But it seems the right of passage for every project to build their own custom environment that never quite works right.
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
If you have the money many projects have found Clear Case a good system. Perfectly workable systems have been build on top of GNU make and CVS. CVS is a freeware build environment built on top of RCS. Its main difference from RCS is that is supports a shared file model to building software.
----------------------------------------------------------------------------
Create a Bug Tracking System Early and Not Often
The earlier people get used to using a bug tracking system the better. If you are 3/4 through a project and then install a bug tracking system it won't be used. You need to install a bug tracking system early so people will use it.
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.
Not sexy things, just good solid project improvements.
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
Several projects have found DDTS a workable system (I 've not verified this link for this PHP release, DDTS may not work for PHP). There is also a GNU bug tracking system available. Roll your own is a popular option but using an existing system seems more cost efficient.
----------------------------------------------------------------------------
Honor Responsibilities
Responsibility for software modules is scoped. Modules are either the responsibility of a particular person or are common. Honor this division of responsibility. Don't go changing things that aren't your responsibility to change. Only mistakes and hard feelings will result.
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文件扩大名
我见过很多种PHP文件的扩大名（.html, .php, .php3, .php4, .phtml, .inc, .class...）
一切阅读者可见页面利用.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(); }
在上例中22和19的寄义是甚么呢？假如一个数字改动了，或这些数字只是复杂的毛病，你会怎样想？
利用难以想象的数字是该法式员是专业活动员的主要标记，如许的法式员历来没有在团队情况中任务过，
又或是为了保持代码而不能不做的，不然他们永久不会做如许的事。
你应当用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
OO has been hyped to the extent you'd figure it would solve world hunger and usher in a new era of world peace. Not! OO is an approach, a philosophy, it's not a recipe which blindly followed yields quality.
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
How many methods should an object have? The right answer of course is just the right amount, we'll call this the Goldilocks level. But what is the Goldilocks level? It doesn't exist. You need to make the right judgment for your situation, which is really what programmers are for :-)
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
2000-11-16. Release
----------------------------------------------------------------------------Copyright 1995-2000. Todd Hoff and Fredrik Kristiansen. All rights reserved.
----------------------------------------------------------------------------
http://www.hooday.com/html/PHP%20Coding%20Standard_cn.htm 既然选择了PHP，就要坚持学下去！大家有没有问自己为什么会选择学习PHP呢？就我个人而言，完全是因为兴趣，因为我的专业和计算机完全无关，但是就是对编程很赶兴趣，尤其对网络编程、web开发特别赶兴趣。 |
|
|Archiver|手机版|仓酷云
鄂ICP备14007578号-2
发表于 2015-2-4 00:20:01
收藏
转播
分享
淘帖
顶
踩
提升卡
置顶卡
沉默卡
喧嚣卡
变色卡
千斤顶
照妖镜
窥视卡
雷达卡
发表于 2015-3-8 13:31:44