远程数据模块文件的名称应当表达出远程数据模块的用途。名称后要加RDM后缀。例如，Customers远程数据模块的文件叫CustomersRDM.dfm。

3.4.5.单元文件

1). 普通单元

(1) 单元名

  单元的名称应当有描述性。例如，应用程序的主窗体单元叫MaimFrm.pas。

(2) Uses 子句

  Interface部分的Uses子句应当只包含该部分需要的单元。不要包含可能由Delphi自动添加的单元名。Implementation部分的Uses子句应当只包含该部分需要的单元，不要有多余的单元。

(3) Interface 部分

  Interface部分应当只包含需要被外部单元访问的类型、变量、过程与函数的声明。而且，这些声明应当在Implementation部分之前。

(4) Implementation 部分

  Implementation部分包括本单元私有的类型、变量、过程与函数的实现。

(5) Initialization 部分

  不要在Initialization部分放置花费时间很多的代码。否则，将导致应用程序启动时显得很慢。

(6) Finalization 部分

  确保释放所有在Initialization部分中分配的资源。

2).窗体单元

  窗体单元文件的名称与相应的窗体名称相同，只是要将前缀变成后缀。例如，About窗体的单元名称叫AboutFrm.pas。主窗体的单元文件名称叫MainFrm.pas。

3).数据模块单元

  数据模块单元文件的名称与相应的数据模块名称相同。例如，数据模块单元的名称叫CustomersDM.pas。

4).通用单元

  通用单元是用于存放函数库，一般类型，或常量而非元件的单元。通用单元的名称应当表达出它的用途，名称前要加“u”前缀。例如，一个实用调试工具单元的名称叫uDebugUtilities.pas，包含全局变量的单元名称叫uCustomerGlobals.pas。

注意，一个项目中单元名称必须是唯一的。通用单元名不能重名。

5).元件单元

(1). 命名

  元件单元应放在单独的路径中，以表明它们是定义元件的单元。它们一般与项目不放在同一路径下。单元文件名称应表达出其内容。

注意，有关元件命名标准的更多信息，请参阅“元件类型的命名标准”。

  元件单元只能含有一个主要元件，这是指出现在元件选项板上的元件。其他辅助性的元件或对象也可以包含在同一单元中。

(2). 注册单元

  元件的注册过程应当从元件单元中移走，放在一个单独的单元中。这个注册单元用于注册所有元件、属性编辑器、元件编辑器、向导等。

  元件注册应当在设计期包中进行。因此，注册单元应当包含在设计期包而不是运行期包中。建议注册单元这样命名：

xxxReg.pas

其中，xxx字符前缀，以标识元件包名称或公司、个人、其他实体。例如，注册单元命名为xxxReg.pas。

6).包文件（.dpk）命名规则

(1). 运行期包与设计期包

  运行期包中应当只包含所需要的单元。那些属性编辑器和元件编辑器的单元应当放在设计期包中。注册单元也应当放在设计期包中。

(2). 文件命名标准

  包的命名遵循下列模式：

dcliiiDescvvCn.pkg —设计期包
iiiDescvvCn.pkg    —运行期包

  其中，iii代表一个2-3字符的前缀，用于标识公司、个人或其他需要标识的事情，也可不要；Desc表示该控件包的简短描述；vv代表包的版本号，你可以根据需要取舍；前缀“dcl”表示设计期包，没有该前缀表示运行期包；字母“Cn”表示编译器类型与编译器版本号，如：Delphi5=D5, Delphi4=D4, CBuilder3=C3...。

注意包名称中的lib或std分别表示这是设计期包还是运行期包。例如：

dclrbStdCompsD5.pkg —Delphi 5的设计期包
rbStdCompsD5.pkg     —Delphi 5的运行期包

4.源程序文档注释规范

我们将通过文档（源程序文件联机注释）定义标准的Delphi 类（函数等）的概要设计规范（official Delphi Class API Specification），以及定义Delphi 类（函数等）的编程指南手册。因此，我们可以以两种方式来写程序文档（注释），一是作为概要设计的规范，二是作为编程手册。两种程序文档既有差别，又有它们共同的地方，因此，它们可以同时写在源程序文档注释中，它们两者的差别在下面有说明。

编写 Delphi 概要设计规范

TODO: <略>

编写编程指南文档

在概要设计规范的基础上，增加了教程，例子程序，等等，并对目录结构进行了重新设计组织和整理。

注释文档的一般规范

注释位置

为源程序的相关元素添加文档注释很简单，你只需要将注释放在元素的声明（Interface）部分（如果是接口函数或类方法）或实现（implementation）部分（如果是私有函数）。例如：

(for Object Pascal)

   { The Sort function sorts the list.}
   function MyList.Sort(Options: Integer): BOOLEAN;
   begin
     [...]
   end;

(for C++)

   // The Sort function sorts the list.
   bool MyList::Sort(int Options)
   {
     [...]
   }

注释块

   // This is the first sentence.
   // This is the second,
   // and this the third

而下面的注释则是两个注释块，因为它们之间有一个空行把它们分开了：

   // This is the first sentence.

   // This is the second,
   // and this the third

许多文档注释分析工具（如：Doc-O-Matic）会将注释块内的所有的句子自动连接在一起，形成一文字段落，如：

   // This is the first sentence.
   // This is the second,
   // and this the third

经过分析工具生成的文档文本为：

   This is the first sentence. This is the second, and this the third.

忽略文档注释

当注释行前用“##”开头时，该行注释将被文档注释分析工具忽略，该行不会生成到文档中。如：

   //## This line will be ignored.

包含有如下标识符的注释块也不会被生成到文档中去：

"Ignore Text", "$Log", "$Filename", "$Revision", "$Date", "$Author", "$History", "$Id"

单元文件注释文档格式

用于描述该单元的用途，作者，功能。放于单元文件的最前面：

{
  ##Unit Name: %UNIT%
  ##Initial Date: %DATE%
  Summary
    该单元的摘要说明。

  Description
    该单元的详细说明。

  See Also
    参阅

  Bugs
    已知问题。

  Internal
    内部开发人员参阅，不会对外。

  TODO
    待作事项。

  Author
    Riceball LEE(riceball@cq118.com)
    Riceball LEE(riceballl@hotmail.com)

  Copyright
    Copyright(C) %YEAR% by Riceball LEE

  Current Version
    当前版本号

  History
    版本历史。
}


unit xxx;

函数（属性）的注释文档格式

{
  ##Procedure: %PROCNAME%
  ##Date:      %DAY%-%MONTHSHORTNAME%-%YEAR%
  Summary
    该函数（属性）的摘要说明。

  Parameters
    %ARGUMENTS%

  Returns
    %RESULT%

  Conditions
    调用该方法（函数）可能需要的条件

  Exceptions
    该方法（函数）有可能触发的异常。

  Description
    该函数（属性）的详细说明。

  See Also
    参阅

  Bugs
    已知问题。

  Internal
    内部开发人员参阅，在正式发布的文档中不会发布。

  TODO
    待作事项。

  Author
    Riceball LEE(riceball@cq118.com)
    Riceball LEE(riceballl@hotmail.com)

  Copyright
    Copyright(C) %YEAR% by Riceball LEE

  Current Version
    当前版本号

  History
    版本历史。
}

function xxx;

5.Delphi代码自动格式化工具

尽管大多数的代码自动格式化工具能够帮你重排源程序格式，以及更新保留字和标示符的大小写，但是这最好在使用版本控制前进行，如果你已经使用了版本控制，建议你不要轻易使用代码自动格式化工具，哪怕多一个空格，版本控制工具也会认为该行已被修改，从而给程序管理带来不变。

6.代码标准文档更新

关于Delphi代码标准的最新文档，你可以在 http://dev.cq118.com/web/ 处获得。

7.参考

Delphi 程序设计编码规范 For 《Delphi Development Guide》(E)

Pascal Standards FAQ (E)

JavaDoc （E）

Doc-O-matic Document (E)

Artemis Alliance Delphi Coding Standards (E)

Borland官方Object Pascal书写风格指南 (E)

上一页  [1] [2] [3]