If Then Else 格式
布局
這由程序員決定。不同的花括號(hào)樣式會(huì)產(chǎn)生些微不同的樣觀。一個(gè)通用方式是：
 if (條件1) // 注釋
 {
 }
 else if (條件2)// 注釋
 {
 }
 else // 注釋
 {
 }
如果你有用到else if 語句的話，通常最好有一個(gè)else塊以用于處理未處理到的其他情況�？梢缘脑�
放一個(gè)記錄信息注釋在else處，即使在else沒有任何的動(dòng)作。
條件格式
總是將恒量放在等號(hào)/不等號(hào)的左邊，例如：
if ( 6 == $errorNum ) ...
一個(gè)原因是假如你在等式中漏了一個(gè)等號(hào)，語法檢查器會(huì)為你報(bào)錯(cuò)。第二個(gè)原因是你能立刻找到數(shù)值
而不是在你的表達(dá)式的末端找到它。需要一點(diǎn)時(shí)間來習(xí)慣這個(gè)格式，但是它確實(shí)很有用。
--------------------------------------------------------------------------------
switch 格式
Falling through a case statement into the next case statement shall be permitted as long as a comment is included.
default case總應(yīng)該存在，它應(yīng)該不被到達(dá)，然而如果到達(dá)了就會(huì)觸發(fā)一個(gè)錯(cuò)誤。
如果你要?jiǎng)?chuàng)立一個(gè)變量，那就把所有的代碼放在塊中。
例如
 switch (...)
 {
case 1:
 ...
// FALL THROUGH
case 2:
{
 $v = get_week_number();
 ...
}
break;
default:
 }
--------------------------------------------------------------------------------
continue,break 和 ? 的使用:
Continue 和 Break
Continue 和 break 其實(shí)是變相的隱蔽的 goto方法。
Continue 和 break 像 goto 一樣，它們在代碼中是有魔力的，所以要節(jié)儉（盡可能少）的使用它們。
使用了這一簡單的魔法，由于一些未公開的原因，讀者將會(huì)被定向到只有上帝才知道的地方去。
Continue有兩個(gè)主要的問題：
它可以繞過測試條件。
它可以繞過等/不等表達(dá)式。
看看下面的例子，考慮一下問題都在哪兒發(fā)生：
while (TRUE)
{
 ...
 // A lot of code
 ...
 if (/* some condition */) {
continue;
 }
 ...
 // A lot of code
 ...
 if ( $i++ > STOP_VALUE) break;
}
注意："A lot of code"是必須的，這是為了讓程序員們不能那么容易的找出錯(cuò)誤。
通過以上的例子，我們可以得出更進(jìn)一步的規(guī)則：continue 和 break 混合使用是引起災(zāi)難的正確方法。
?:
麻煩在于人民往往試著在 ? 和 : 之間塞滿了許多的代碼。以下的是一些清晰的連接規(guī)則：
把條件放在括號(hào)內(nèi)以使它和其他的代碼相分離。
如果可能的話，動(dòng)作可以用簡單的函數(shù)。
把所做的動(dòng)作，“?”，“:”放在不同的行，除非他們可以清楚的放在同一行。
例如
 (condition) ? funct1() : func2();
 or
 (condition)
? long statement
: another long statement;
--------------------------------------------------------------------------------
聲明塊的定位
聲明代碼塊需要對齊。
理由Justification
清晰。
變量初始化的類似代碼塊應(yīng)該列表。
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;
--------------------------------------------------------------------------------
每行一個(gè)語句
除非這些語句有很密切的聯(lián)系，否則每行只寫一個(gè)語句。
--------------------------------------------------------------------------------
短方法
方法代碼要限制在一頁內(nèi)。
理由
這個(gè)思想是，每一個(gè)方法代表著一個(gè)完成單獨(dú)目的的技術(shù)。
從長遠(yuǎn)來說，過多的無效參數(shù)是錯(cuò)誤的。
調(diào)用函數(shù)比不調(diào)用要慢，但是這需要詳細(xì)考慮做出決定（見premature optimization 未完善的優(yōu)化）。
--------------------------------------------------------------------------------
記錄所有的空語句
總是記錄下for或者是while的空塊語句，以便清楚的知道該段代碼是漏掉了，還是故意不寫的。
 while ($dest++ = $src++)
; // VOID
--------------------------------------------------------------------------------
不要采用缺省方法測試非零值
不要采用缺省值測試非零值，也就是使用：
 if (FAIL != f())
比下面的方法好：
 if (f())
即使 FAIL 可以含有 0 值 ，也就是PHP認(rèn)為false的表示。在某人決定用-1代替0作為失敗返回值的時(shí)候，
一個(gè)顯式的測試就可以幫助你了。就算是比較值不會(huì)變化也應(yīng)該使用顯式的比較；例如：if (!($bufsize % strlen($str)))
應(yīng)該寫成：if (($bufsize % strlen($str)) == 0)以表示測試的數(shù)值（不是布爾）型。一個(gè)經(jīng)常出
問題的地方就是使用strcmp來測試一個(gè)字符等式，結(jié)果永遠(yuǎn)也不會(huì)等于缺省值。
非零測試采用基于缺省值的做法，那么其他函數(shù)或表達(dá)式就會(huì)受到以下的限制:
只能返回0表示失敗，不能為/有其他的值。
命名以便讓一個(gè)真(true)的返回值是絕對顯然的，調(diào)用函數(shù)IsValid()而不是Checkvalid()。
--------------------------------------------------------------------------------
布爾邏輯類型
大部分函數(shù)在FALSE的時(shí)候返回0，但是發(fā)揮非0值就代表TRUE，因而不要用1（TRUE，YES，諸如此類）等式檢測一個(gè)布爾值，應(yīng)該用0（FALSE，NO，諸如此類）的不等式來代替：
 if (TRUE == func()) { ...
應(yīng)該寫成：
 if (FALSE != func()) { ...
--------------------------------------------------------------------------------
通常避免嵌入式的賦值
有時(shí)候在某些地方我們可以看到嵌入式賦值的語句，那些結(jié)構(gòu)不是一個(gè)比較好的少冗余，可讀性強(qiáng)的方法。
 while ($a != ($c = getchar()))
 {
process the character
 }
++和--操作符類似于賦值語句。因此，出于許多的目的，在使用函數(shù)的時(shí)候會(huì)產(chǎn)生副作用。使用嵌入式賦值
提高運(yùn)行時(shí)性能是可能的。無論怎樣，程序員在使用嵌入式賦值語句時(shí)需要考慮在增長的速度和減少的可維
護(hù)性兩者間加以權(quán)衡。例如：
 a = b + c;
 d = a + r;
不要寫成：
 d = (a = b + c) + r;
雖然后者可以節(jié)省一個(gè)周期。但在長遠(yuǎn)來看，隨著程序的維護(hù)費(fèi)用漸漸增長，程序的編寫者對代碼漸漸遺忘，
就會(huì)減少在成熟期的最優(yōu)化所得。
--------------------------------------------------------------------------------
重用您和其他人的艱苦工作
跨工程的重用在沒有一個(gè)通用結(jié)構(gòu)的情況下幾乎是不可能的。對象符合他們現(xiàn)有的服務(wù)需求，不同的過程有著
不同的服務(wù)需求環(huán)境，這使對象重用變得很困難。
開發(fā)一個(gè)通用結(jié)構(gòu)需要預(yù)先花費(fèi)許多的努力來設(shè)計(jì)。當(dāng)努力不成功的時(shí)候，無論出于什么原因，有幾種辦法推
薦使用：
請教！給群組發(fā)Email求助
這個(gè)簡單的方法很少被使用。因?yàn)橛行┏绦騿T們覺得如果他向其他人求助，會(huì)顯得自己水平低，這多傻啊!做新
的有趣的工作，不要一遍又一遍的做別人已經(jīng)做過的東西。
如果你需要某些事項(xiàng)的源代碼，如果已經(jīng)有某人做過的話，就向群組發(fā)email求助。結(jié)果會(huì)很驚喜哦！
在許多大的群組中，個(gè)人往往不知道其他人在干什么。你甚至可以發(fā)現(xiàn)某人在找一些東西做，并且自愿為你寫代
碼，如果人們在一起工作，外面就總有一個(gè)金礦。
告訴！當(dāng)你在做事的時(shí)候，把它告訴所有人
如果你做了什么可重用的東西的話，讓其他人知道。別害羞，也不要為了保護(hù)自豪感而把你的工作成果藏起來。
一旦養(yǎng)成共享工作成果的習(xí)慣，每個(gè)人都會(huì)獲得更多。
Don't be Afraid of Small Libraries
對于代碼重用，一個(gè)常見的問題就是人們不從他們做過的代碼中做庫。一個(gè)可重用的類可能正隱蔽在一個(gè)程序目
錄并且決不會(huì)有被分享的激動(dòng)，因?yàn)槌绦騿T不會(huì)把類分拆出來加入庫中。
這樣的其中一個(gè)原因就是人們不喜歡做一個(gè)小庫，對小庫有一些不正確感覺。把這樣的感覺克服掉吧，電腦才不
關(guān)心你有多少個(gè)庫呢。
如果你有一些代碼可以重用，而且不能放入一個(gè)已經(jīng)存在的庫中，那么就做一個(gè)新的庫吧。如果人們真的考慮重
用的話，庫不會(huì)在很長的一段時(shí)間里保持那么小的。
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.
--------------------------------------------------------------------------------
評(píng)價(jià)注釋
注釋應(yīng)該是講述一個(gè)故事
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.
使用標(biāo)頭說明
利用類似ccdoc的文檔抽取系統(tǒng)。在這一文檔的其他部分描述的是怎么利用ccdoc記錄一個(gè)類和方法。
這些標(biāo)頭說明可以以這樣的一個(gè)方式來提取并分析和加以組織，它們不像一般的標(biāo)頭一樣是無用的。
因此花時(shí)間去填上他吧。
注釋布局
工程的每部分都有特定的注釋布局。
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.
--------------------------------------------------------------------------------