Skip to content

DelphiCode.md

Latest commit

 

History

History
115 lines (97 loc) · 5.93 KB

DelphiCode.md

File metadata and controls

115 lines (97 loc) · 5.93 KB

Delphi 代码编写规范与要求

一、基本原则

  1. 设计时优先原则
    • 所有能通过 IDE 属性检查器设置的控件属性，应尽量在设计时完成配置。
    • 避免在运行时动态创建控件或修改控件属性，尤其是在界面初始化和事件处理时。
    • 经常检查pas和dfm中的控件和属性声明是否匹配；增加相应的声明；
    • 编译前先检查每一个文件pas是否有中文乱码，有的话，请修复，修复后用utf8+bom来保存文件；
  2. 架构规范
    • 采用 MVC（模型-视图-控制器）架构 + Helper + Utils 设计模式，确保代码逻辑清晰，职责分明。
    • 主Form 仅负责界面更新和视图展示，逻辑处理应分离到独立的控制器和辅助类中。
    • 所有数据库操作应集中在 uDM.pas 数据模块中，确保数据库访问与其他逻辑代码的分离。
  3. 参数传递规范
    • 在函数或方法调用时，优先传递数据结构体而非控件对象，减少对 UI 控件的耦合。
    • 跨单元调用时，必须显式指定单元名前缀，以增强代码的可读性和可维护性。

二、文件组织规范

  1. 命名规则
    • 文件命名采用统一格式：类别前缀+功能描述.pas。
    • 常见类别前缀：
      • Model：数据模型相关
      • Helper：功能辅助类
      • Utils：通用工具类
      • Ctrl：控制器
    • 示例：
      • ModelConfig.pas（数据模型）
      • HelperMenu.pas（功能辅助类）
      • UtilsLog.pas（日志工具）
      • CtrlMain.pas（主控制器）
  2. 目录结构
    • 所有代码文件放在项目根目录，不得创建二级目录。
    • 保持项目文件简洁，便于查找和管理。
    • 数据模块文件应命名为 uDM.pas，并且存放在项目根目录中。
    • 主Form文件应保持默认命名（如 Unit1.pas），不进行修改。

三、编码规范

  1. 类型定义
    • 所有类型、数据结构和常量（CONST）定义必须集中放置在 UtilsTypes.pas 中，以便共享。
    • 记录类型命名：T + 描述（如 TUserInfo）。
    • 类类型命名：T + 描述（如 TConfigModel）。
  2. 变量命名
    • 私有变量：使用 a 或 the 前缀（如 aTreeNode、theConfigData），避免与局部变量或成员变量冲突。
    • 控件变量：使用控件类型缩写 + 用途描述（如 btnSubmit、edtPassword）。
    • 避免使用无意义的短变量名（如 i、j）。命名应具有清晰的语义。
  3. 方法调用
    • 跨单元调用时，必须添加单元名前缀以增强代码可读性（如 UtilsLog.WriteLog）。

四、常见错误指南

  1. 架构错误
    • ❌ 问题：在 Form 中直接编写 SQL 语句或进行数据库操作。
    • ✅ 解决方案：应将所有数据库操作移至 uDM.pas 数据模块。
  2. 参数传递错误
    • ❌ 问题：传递控件对象作为参数（如 procedure UpdateUI(AListBox: TListBox)）。
    • ✅ 解决方案：应传递数据结构体而非控件对象（如 procedure UpdateUI(const AData: TListData)）。
  3. 控件使用错误
    • ❌ 问题：在运行时动态创建大量控件，导致界面加载性能问题。
    • ✅ 解决方案：在设计时完成控件创建和基础属性设置，避免动态创建控件。
  4. 目录结构错误
    • ❌ 问题：在项目中创建 /models、/controllers 等子目录。
    • ✅ 解决方案：所有代码文件应平铺在项目根目录，不要创建不必要的目录。
  5. 命名错误
    • ❌ 问题：私有变量命名如 TreeItem，容易与其他局部变量或成员变量冲突。
    • ✅ 解决方案：使用 a 或 the 前缀进行命名，如 aTreeItem 或 theTreeItem。
  6. 类型定义错误
    • ❌ 问题：在不同单元中重复定义相同结构体。
    • ✅ 解决方案：所有类型定义应集中在 UtilsTypes.pas 中，避免重复定义。
  7. 方法调用错误
    • ❌ 问题：调用方法时没有加上单元前缀（如 WriteLog('error')）。
    • ✅ 解决方案：始终使用单元名前缀进行调用，如 UtilsLog.WriteLog('error')。

五、版本控制建议

  1. 提交代码前检查：
    • 是否存在动态创建控件，且无法有效管理控件生命周期。
    • 是否在 UtilsTypes.pas 中集中定义了私有类型、常量和数据结构。
    • 所有跨单元调用是否正确添加了单元前缀。
    • 是否传递了控件对象而非数据结构体。
  2. 代码审查重点关注：
    • Form 文件是否包含业务逻辑代码，是否违反了架构分层原则。
    • 是否存在重复的类型定义，避免类型定义混乱。
    • 参数传递是否符合规范，是否过度依赖控件对象而非数据结构。

Delphi 常见错误列表

  1. 动态创建控件后未释放
    • 错误：在运行时动态创建控件，却没有妥善管理其生命周期，导致内存泄漏。
    • 解决：动态创建控件时应配合 Free 方法释放，避免内存泄漏。
  2. 访问控件属性时未检查其是否已创建
    • 错误：在运行时访问尚未创建的控件属性，导致程序崩溃。
    • 解决：访问控件属性前应先检查控件是否存在。
  3. 数据库连接未关闭
    • 错误：未正确关闭数据库连接，导致连接泄漏。
    • 解决：使用 try...finally 语句确保数据库连接的正确关闭。
  4. 使用无效的 try...except 语句
    • 错误：捕获错误后未处理异常，导致错误被吞掉或忽略。
    • 解决：在 except 块中进行适当的错误处理和日志记录。
  5. 变量作用域错误
    • 错误：变量在不同作用域中重复定义，导致变量值混乱或覆盖。
    • 解决：确保变量的作用域清晰，并遵循命名规范。