Project JEDI VCL组件编码标准

 

编写该标准的目的是统一组件代码的书写格式,以便于所有的Delphi程序员----无论是初学者还是高级开发人员---都能够方便地维护和理解他们。对于某些并不完全符合标准，但是十分优秀并且已经加入到源代码知识库的组件，我们在审阅的时候会给予一定的灵活度。然而任何一个程序员在提交他们的代码时，都应该附带正确的题头和说明文档，并认真填写，这一点极为重要。这项工作会让你的代码更容易被源代码知识库采用。

原则上,我们将遵循Charlie Calvert先生在Borland Techvoyage 站点中发表的 Delphi编码风格指导中所采用的规范。

5.1 组件代码必须包含的信息

5.1.1题头（作者姓名/等，版本控制信息）

任何提交给知识库的源码文件的最开头部分，都必须附有如图1中所显示的题头格式，该格式对Borland Delphi 和 Borland C++Builder 均有效。

{-----------------------------------------------------------------------------
The contents of this file are subject to the Mozilla 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
http://www.mozilla.org/MPL/

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 http://www.delphi-jedi.org

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

图1 标准组件题头

 图中“The Original Code” 一栏中的 “XXX.PAS” 代表源文件名.通常情况下,源文件名同你所开发的组件名是不同的.举例来说,一个名为TJvScreen的组件应该包含在名为Screen.pas的文件中。作为约定，源文件 （.pas）不应包含“TJv”或“Jv”前缀。

 “Initial Developer”一栏中应包含有原作者全名，以及邮件地址。为了方便Bug的修正和其它联系，留下一个邮件地址是很重要的。

5.1.2 Mozilla 许可协议放弃声明

原作者只允许使用5.1.1中采用的标准题头.如果没有特别声明放弃该协议，源文件将不被采纳.    

有一种情况例外，那就是当代码放置在公共域中时，在这种情况下，请将Mozilla 许可协议替换成下面的声明。

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

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

The Initial Developer of the Original Code is Joe Doe <Joe.doe@email.com>.

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 http://www.delphi-jedi.org

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: TObject;       
     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.com 的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中止（可能的话）。

·使用绝对跳转标识将被认为是不好的编码风格（汇编除外）。