Project JEDI VCL元件編碼標準 (轉)

Project JEDI VCL元件編碼標準 (轉)[@more@] 

編寫該標準的目的是統一程式碼的書寫格式,以便於所有的員----無論是初學者還是高階開發人員---都能夠方便地維護和理解他們。對於某些並不完全符合標準，但是十分優秀並且已經加入到知識庫的元件，我們在審閱的時候會給予一定的靈活度。然而任何一個程式設計師在提交他們的程式碼時，都應該附帶正確的題頭和說明文件，並認真填寫，這一點極為重要。這項工作會讓你的程式碼更容易被原始碼知識庫採用。:namespace prefix = o ns = "urn:schemas--com::office" />

原則上,我們將遵循CharlCalvert先生在pbox/techvoyage/article/1,1795,10280,00.html">Borland Techvoyage 站點中發表的 Delphi編碼風格指導中所採用的規範。

5.1 元件程式碼必須包含的資訊

5.1.1題頭（作者姓名/等，版本控制資訊）

任何提交給知識庫的原始碼的最開頭部分，都必須附有如圖1中所顯示的題頭格式，該格式對Borland Delphi 和 Borland C++Builder 均有效。

{-----------------------------------------------------------------------------
The contents of this file are subject to the Public License
Version 1.1 (the "License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either expressed or implied. See the License for
the specific language governing rights and limitations under the License.

The Original Code is: XXX.PAS, released 2000-06-15.

The Initial Developer of the Original Code is Joe Doe joe.doe@email.com>
Portions created by Joe Doe are Copyright (C) 1999 Joe Doe.
Portions created by Microsoft are Copyright (C) 1998, 1999 Microsoft Corp.
All Rights Reserved.

Contributor(s): ______________________________________.

Last Modified: 2000-mm-dd;
Current Version: X.XX

You may retrieve the latest version of this file at the Project JEDI home page,
located at

Known Issues:
-----------------------------------------------------------------------------}

圖1 標準元件題頭

 圖中“The Original Code” 一欄中的 “XXX.PAS” 代表原始檔名.通常情況下,原始檔名同你所開發的元件名是不同的.舉例來說,一個名為TJvScreen的元件應該包含在名為Screen.pas的檔案中。作為約定，原始檔 （.pas）不應包含“TJv”或“Jv”字首。

 “Initial Developer”一欄中應包含有原作者全名，以及地址。為了方便的修正和其它聯絡，留下一個郵件地址是很重要的。

5.1.2 Mozilla 許可放棄宣告

原作者只允許使用5.1.1中採用的標準題頭.如果沒有特別宣告放棄該協議，原始檔將不被採納. 

有一種情況例外，那就是當程式碼放置在公共域中時，在這種情況下，請將Mozilla 許可協議替換成下面的宣告。

{-----------------------------------------------------------------------------
This is an original work by Joe Doe and is hereby placed in the Public ain.

The Original Code is: XXX.PAS, released 2000-06-15.

The Initial Developer of the Original Code is Joe Doe <>.

Contributor(s): ______________________________________.

Last Modified: 2000-06-15
Current Version: X.XX

You may retrieve the latest version of this file at the Project JEDI home page,
located at

Known Issues:
-----------------------------------------------------------------------------}

5.1.3 過程/塊

原作者同樣需要對每一個過程或函式附加詳細的說明。說明的文字要有正確的縮排：

{------------------------------------------------------------------------------
  Procedure: TJvScreen.DemoEventHandler
  Description:
  Author: Joe Doe
 Date created: 3/1/1996
Date modified: mm/dd/yyyy by Joe Foo
  Purpose:
 Known Issues:
 ------------------------------------------------------------------------------}

procedure TJvScreen.DemoEventHandler(
  Sender: T; 
  Col  : LongInt; 
  Row  : Longint; 
  Rect  : TRect; 
  State : TGridDrawState);  // Refer to notes

var
  i,
  j,
  ThisNum,
  ThatNum: integer;
  IsAlive,
  IsPurple: Boolean;

begin
(?
end;

  圖 2 – 標準函式/過程塊

5.1.4 原始碼中字首的用法

下列是我們所推薦的字首編碼方法:

元件字首(例：TJvHtmlHelp)  要求

成員字首(例：FDefaultWindow)  要求

類字首(例：TJvHtmlHelpRouter)  要求

全域性變數字首(例：GHtmlHelpRouter)  要求

指標字首(例：PMyPointer)  要求

指標變數字首(例：PopupDefsPtr)  要求

列舉型別字首(例：alBottom)  要求

其他字首  不要求

5.1.5  斷言

 在原始碼中插入斷言（對過程/函式的一些簡短的預處理和後處理）是值得提倡的編碼方法。這樣做有助於最終更清楚的瞭解元件作者的意圖。斷言只在Delphi的整合環境中被程式，而不會編譯到最終的版本中，因而使用起來不需要有任何顧慮。

  5.2 元件名稱

所有的 Jedi-VCL 元件都使用標準的“TJv”字首以和其他元件相區別（請注意大寫“J”）。TJv已經在developers.href.的Delphi字首序號產生器構登記，隸屬於Project JEDI。

 5.3 原始碼庫管理人員修改元件名的

某些提交上來的元件要麼同原始碼庫的另一個元件重名,要麼名稱或字首不恰當.舉例來說，一個功能是向螢幕上輸出字元而命名為TJvPrint的元件就不符合要求，因為Print容易讓人聯想到印表機。基於以上的考慮，原始碼庫管理人員有責任修改某些元件的名稱，以使元件命名更加清楚明瞭或保證命名的唯一性。

5.3.1 在元件釋出之後修改名稱

一旦元件被選中並加入到原始碼庫中後,其名稱就應該固定. 允許修改名稱可能會產生不必要的麻煩,尤其對於那些正在使用舊的名稱而又沒有及時的使用者.

5.4 原始碼格式

Borland Delphi 的程式碼格式必須同當前Borland公司為Delphi VCL定義的編碼標準相一致。如前所述，原則上,我們將遵循Charlie Calvert先生在Delphi編碼風格指導中的規範。這樣做的目的是為了向所有的Borland Delphi開發人員提供一種他們能夠識別的統一格式。背離基本的規範是我們所要避免的。

5.5 程式碼中的註釋

對方法功能的註釋最好不要超過一行.註釋是用來解釋程式碼的,而不是告訴別人怎麼使用它.在一個方法中，要儘量做到只在需要解釋的程式碼後加入註釋.而不要這樣

Form.Show //Show Form

  作為參考，儘量保持每十行程式碼對應一行註釋的比率。

5.6 其它

·空格：在逗號和冒號後要加空格，運算子（+, -, *, /, := , = , 等）兩邊也應有空格。

·同一行內不允許有多個命令或變數宣告。

·對於沒有註釋的方法，至少要用分割線（如：//-----80個字元寬） 將其相互隔開。對每一個方法通常都是不需要註釋的，例如，一個名為CountErrors的方法便不需要註釋。

·對於複雜的邏輯或數學儘量使用括號以增加可讀性，儘管從語法的角度上來講不一定需要。

·在邏輯表示式中和其他一些容易導致跟蹤上的困難的地方應該最大限度的避免函式的使用。

·對指標變數顯式的撤銷呼叫（如 MyDynamicArray^[0]）不再需要,並且在任何時候都應儘量避免。

·結構化函式的使得函式只在一點結束(End關鍵字處)而不是被exit中止（可能的話）。

·使用絕對跳轉標識將被認為是不好的編碼風格（除外）。