Delphi Spring Framework编程规范(草稿)V0.1

计胤
2023-12-01

 

Delphi Spring Framework编程规范(草稿)V0.1 (更新日期:2009-10-28)

1. 前言

为保证Delphi Spring Framework项目代码的可读性质量,特建立本编程规范。本规范仅适用于Delphi Spring Framework各项目成员,大家如有任何意见和建议,请给我留言。

2. 所有项目文件、单元文件和示例程序必须包含下列版权声明:

{***************************************************************************}
{                                                                           }
{           Delphi Spring Framework                                         }
{                                                                           }
{           Copyright (C) 2009-2010 Delphi Spring Framework                 }
{                                                                           }
{           http://delphi-spring-framework.googlecode.com                   }
{                                                                           }
{***************************************************************************}
{                                                                           }
{  Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0                           }
{                                                                           }
{  Unless required by applicable law or agreed to in writing, software      }
{  distributed under the License is distributed on an "AS IS" BASIS,        }
{  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. }
{  See the License for the specific language governing permissions and      }
{  limitations under the License.                                           }
{                                                                           }
{***************************************************************************}

3. 命名规范

  • 核心单元文件均采用Spring.*.pas的命名方式,如:Spring.System.pas;
  • 类、记录、枚举、集合以及自定义类型以T开始,如TSimpleClass、TDriveType;
  • 接口类型一律以I开头,如IEnumerable,IList<T>;
  • 异常类以E开头,如EArgumentException,EFileNotFoundException;
  • 资源字符串(resourcestring)以S作为前缀,如SFileNotFound;
  • 类字段成员、局部变量和参数应采用Camel风格,如fOperatingSystem, i, value, targetStream;
  • 类的属性和方法一律采用Pascal风格,Boolean型属性应使用Is前缀,如Name,IsReadOnly,IsValid,IsEmpty,GetNextID;
  • 抽象基类尽可能使用Base作为后缀,如TCollectionBase,TStreamBase;
  • 自定义属性类名无需前缀T(抽象属性基类则应保留),且以Attribute作为后缀,如:
    DisplayNameAttribute
    = class(TCustomAttribute)
    private
      fName
    : string;
    public
     
    constructor Create(const name: string);
    end;
    应用属性时一般省略后缀Attribute,如:
    [DisplayName(‘Paul’)]
    TSomeClass
    = class
    end;
  • 所有保留字全部小写,如procedure,string,begin,end等。

4. 缩进及换行

使用标准Pascal的缩进和换行方式,如:

for i := 0 to list.Count-1 do
begin
  if condition then
  begin
    DoSomething;
  end
  else
  begin
    //...
  end;
  case driveType of
    dtNetwork:
    begin
      //...
    end;
    else
    begin
      //...
    end;
  end;
end;

5. 使用Xml的风格注释

  ///
  /// Provides version information for a physical file on disk.
  ///
  ///
  /// Remarks
  ///
  TFileVersionInfo = record
  //...
  end;

注意:为便于各地开发者阅读和使用代码,请使用英文。

6. 必须检查全局函数和所有公开的方法的参数合法性

Spring.System.TArgument类提供了很多静态方法用来检查参数,如CheckTrue,CheckFalse,CheckRange等。(可使用代码模板减少输入)

7. 全局变量、全局函数以及公开的静态类方法尽可能是线程安全的

如不支持线程安全必须注明。

8. 编写的代码必须支持Unicode

注意:RTL中有些函数并不支持Unicode,如:

SysUtils.UpperCase

仅支持标准7位Ascii码中’a’-‘z’的大小写转换,应使用Character.TCharacter类的ToUpper和ToLower方法

SysUtils.LowerCase

 

SysUtils.BytesOf

应使用WideBytesOf

SysUtils.StringOf

应使用WideStringOf

9. 除非特别需求,否则永远不要把下列类型的文件上传到svn服务器:

  • *.bak
  • *.dcu
  • *.exe
  • *.~*
  • *.ddp
  • *.dsk
  • *.local
  • *.identcache
  • *.tvsconfig
  • · __history (文件夹)

10. 其他建议

  • 尽可能将参数定义成constvarout
  • 应将抽象基类标记为abstract
  • 工具类(utility class)应优先考虑使用record来实现
  • 尽可能保证每个过程职责清晰,一般不超过20行代码
  • 尽可能保证代码是可测试的,并使用DUnit编写单元测试用例
  • 尽可能保持版本兼容性,使用deprecated, experimental等关键字提醒开发者
  • 谨慎使用class constructor和class destructor代替单元的初始化(initialization)和终止化(finalization)
  • 抛异常时优先使用Exception.CreateRes(@SResourceString)等方法

作者:左保权 (Paul)

 类似资料: