VBMAN 项目编码风格和规则

本文档总结了 VBMAN 项目的编码风格和规则,供 AI 编码参考


一、项目概述

VBMAN 是一个基于 VB6 的工具类库项目,提供网络通信、数据库、协议实现(Modbus、WebSocket 等)、工具类等通用功能。

项目结构:

src/
  ├── [功能模块]/          # 功能目录
  │   ├── c[Name].cls      # 主要类文件(如 cModbusMaster.cls)
  │   ├── m[Name].bas      # 模块文件(如 mModbus.bas)
  │   └── [子目录]/        # 子功能
  └── StaticClass/         # 静态类
      ├── cVBMAN.cls
      └── sGlobal.cls

二、命名规范

2.1 类文件命名 (.cls)

格式: c[功能描述].cls

示例:

  • cModbusMaster.cls - Modbus 主站类
  • cHttpClient.cls - HTTP 客户端类
  • cWebSocketServer.cls - WebSocket 服务器类
  • cAsyncSocket.cls - 异步 Socket 类

规则:

  • 使用 c 前缀(Class)
  • 采用 Pascal 命名法(首字母大写,每个单词首字母大写)
  • 功能描述要清晰明确

2.2 模块文件命名 (.bas)

格式: m[功能描述].bas 或 md[功能描述].bas

示例:

  • mModbus.bas - Modbus 公共模块
  • mdTlsNative.bas - TLS 原生实现模块
  • ToolsArray.bas - 数组工具模块

规则:

  • 使用 m 前缀(Module)
  • md 用于较底层/原生代码模块
  • 采用 Pascal 命名法

2.3 类名命名

格式: c[功能描述]

示例:

VERSION 1.0 CLASS
Attribute VB_Name = "cModbusMaster"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = True
Attribute VB_PredeclaredId = False
Attribute VB_Exposed = True

规则:

  • 类名与文件名保持一致
  • Attribute VB_Creatable = True 用于可外部创建的类
  • Attribute VB_Exposed = True 用于 COM 暴露的类

2.4 成员变量命名

私有成员变量: m_[类型前缀][描述]

变量类型 前缀 示例
Boolean b m_bConnected
Byte b m_SlaveID
Integer i / n m_iCount, m_nRetries
Long l m_Timeout, m_lIndex
Double dbl m_Temperature
String s / m_ m_Host, m_ApiKey
Object o m_oHelperWindow
Collection c m_cMsgQueue
Enum/Type 使用类型名 m_ProtocolType, m_Defaults
Boolean (状态) m_ + 描述 m_IsStreaming

示例:

Private m_ApiKey As String
Private m_BaseUrl As String
Private m_Timeout As Long
Private m_Temperature As Double
Private m_IsStreaming As Boolean
Private WithEvents m_TransportTCP As cModbusTransportTCP
Private m_Messages As Collection

规则:

  • 所有成员变量使用 m_ 前缀
  • Boolean 类型状态变量使用 m_Is[状态] 或 m_b[状态]
  • 事件处理对象使用 WithEvents 关键字

2.5 枚举命名

格式: [模块前缀][功能][类型]Enum

示例:

Public Enum ModbusMasterFunctionCode
    MB_MASTER_FC_READ_COILS = &H1
    MB_MASTER_FC_READ_HOLDING_REGISTERS = &H3
End Enum

Public Enum UcsAsyncSocketTypeEnum
    ucsSckStream = 1
    ucsSckDatagram = 2
End Enum

规则:

  • 枚举名描述清晰,使用 Pascal 命名法
  • 枚举值使用大写,用下划线分隔
  • 使用统一前缀(如 MB_MASTER_FC_, ucsSck)
  • 常用前缀:
    • FC_ - Function Code(功能码)
    • STATE_ - State(状态)
    • PROTOCOL_ - Protocol(协议)

2.6 类型定义命名

格式: [功能]Type 或 [功能]Info / [功能]Config

示例:

Public Type ModbusMasterDefaults
    TCP_PORT As Long
    RTU_DEFAULT_BAUDRATE As Long
    MAX_REGISTERS As Long
End Type

Public Type IP_ADAPTER_INFO
    Next As Long
    Index As Long
    Type As Long
End Type

2.7 常量命名

格式: [模块前缀]_[描述] 或全部大写

示例:

Private Const MODULE_NAME As String = "cAsyncSocket"
Private Const DEF_TIMEOUT As Long = 5000
Private Const STR_HELPER_CLASS As String = "STATIC"

规则:

  • 模块级常量使用模块前缀(如 MB_MASTER_FC_, MB_SLAVE_FC_)
  • 私有常量使用 DEF_ 或 STR_ 前缀
  • 全大写,用下划线分隔

2.8 函数/过程命名

格式: [动词][名词] 或 [动词][名词][名词]

示例:

' 公共方法
Public Function ReadCoils(ByVal StartAddress As Long, ByVal Quantity As Long) As Boolean()
Public Sub Connect()
Public Function ApiKey(Key As String) As cAI

' 私有方法
Private Sub ConnectTCP()
Private Function BuildReadRequest(ByVal FC As ModbusMasterFunctionCode, _
                                  ByVal StartAddress As Long, _
                                  ByVal Quantity As Long) As Byte()
Private Sub ValidateQuantity(ByVal Quantity As Long, ByVal MaxQuantity As Long)

规则:

  • 方法名使用 Pascal 命名法
  • 使用动词开头(如 Get, Set, Read, Write, Build, Parse)
  • 私有方法以动作描述为主
  • 链式调用方法返回 Me

2.9 属性命名

格式: [名词]

示例:

Public Property Get State() As ModbusMasterState
Public Property Let State(ByVal Value As ModbusMasterState)
Public Property Get LastError() As String
Public Property Get ApiKey As String

规则:

  • 使用 Pascal 命名法
  • Get/Let/Proc 保持一致
  • Boolean 属性可用 Is 前缀(如 IsConnected, IsClosed)

2.10 参数命名

格式: [类型前缀][描述] 或完整单词

示例:

Public Function ReadCoils(ByVal StartAddress As Long, ByVal Quantity As Long) As Boolean()
Private Sub ParseStreamChunk(Data As String)
Public Function BaseUrl(Url As String) As cAI
Private Function BuildFrame(ByRef PDU() As Byte) As Byte()

规则:

  • 参数名使用 Pascal 命名法
  • ByVal 和 ByRef 明确声明
  • 数组参数使用 ByRef
  • 首字母大写

三、代码组织

3.1 类文件结构模板

VERSION 1.0 CLASS
BEGIN
  MultiUse = -1  'True
  Persistable = 0  'NotPersistable
  DataBindingBehavior = 0  'vbNone
  DataSourceBehavior  = 0  'vbNone
  MTSTransactionMode  = 0  'NotAnMTSObject
END
Attribute VB_Name = "c[类名]"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = True/False
Attribute VB_PredeclaredId = False
Attribute VB_Exposed = True/False

'=========================================================================
'
' [类名] - [简短描述]
'
' Purpose: [详细说明类的用途]
'          - 功能点1
'          - 功能点2
'
' Author: [作者名]
' Date: [创建日期]
'
'=========================================================================

Option Explicit

'=========================================================================
' 依赖引用
'=========================================================================
' [说明依赖的其他类或模块]

'=========================================================================
' 事件定义
'=========================================================================
Public Event On[EventName](参数...)
Public Event OnError(ByVal Description As String)

'=========================================================================
' 枚举定义
'=========================================================================
Public Enum [EnumName]
    [ENUM_VALUE_1] = 1
    [ENUM_VALUE_2] = 2
End Enum

'=========================================================================
' 类型定义
'=========================================================================
Public Type [TypeName]
    [Member] As [Type]
End Type

'=========================================================================
' API 声明
'=========================================================================
Private Declare Function [FunctionName] Lib "[Library]" (参数...) As [Type]

'=========================================================================
' 私有变量
'=========================================================================
Private m_[Variable] As [Type]
Private WithEvents m_[EventObject] As [ClassType]

'=========================================================================
' 属性定义
'=========================================================================

Public Property Get [PropertyName]() As [Type]
    [PropertyName] = m_[Variable]
End Property

Public Property Let [PropertyName](ByVal Value As [Type])
    m_[Variable] = Value
End Property

'=========================================================================
' 公共方法 - [功能分类]
'=========================================================================

Public Function [MethodName](参数...) As [Type]
    On Error GoTo ErrorHandler

    ' 实现代码

    Exit Function
ErrorHandler:
    [错误处理]
End Function

'=========================================================================
' 私有方法 - [功能分类]
'=========================================================================

Private Function [MethodName](参数...) As [Type]
    ' 实现代码
End Function

'=========================================================================
' 事件处理
'=========================================================================

Private Sub [ObjectName]_[EventName](参数...)
    ' 事件处理代码
End Sub

'=========================================================================
' 类事件
'=========================================================================

Private Sub Class_Initialize()
    ' 初始化代码
End Sub

Private Sub Class_Terminate()
    On Error Resume Next
    ' 清理代码
End Sub

3.2 模块文件结构模板

Attribute VB_Name = "m[模块名]"

'=========================================================================
'
' m[模块名] - [简短描述]
'
' Author: [作者名]
' Date: [创建日期]
'
'=========================================================================

Option Explicit

'=========================================================================
' 公共常量
'=========================================================================
Public Const [CONST_NAME] As [Type] = [Value]

'=========================================================================
' 公共枚举
'=========================================================================
Public Enum [EnumName]
    [ENUM_VALUE_1] = 1
End Enum

'=========================================================================
' 公共类型
'=========================================================================
Public Type [TypeName]
    [Member] As [Type]
End Type

'=========================================================================
' API 声明
'=========================================================================
Public Declare Function [FunctionName] Lib "[Library]" (参数...) As [Type]

'=========================================================================
' 公共变量
'=========================================================================
Public g_[Variable] As [Type]

'=========================================================================
' 私有变量
'=========================================================================
Private m_[Variable] As [Type]

'=========================================================================
' 公共函数
'=========================================================================

Public Function [FunctionName](参数...) As [Type]
    ' 实现代码
End Function

'=========================================================================
' 私有函数
'=========================================================================

Private Function [FunctionName](参数...) As [Type]
    ' 实现代码
End Function

3.3 分隔线规范

使用以下分隔线组织代码:

'=========================================================================
' [分类标题]
'=========================================================================

常用分类标题:

  • ' 事件定义
  • ' 枚举定义
  • ' 类型定义
  • ' API 声明
  • ' 成员变量 / ' 私有变量
  • ' 属性
  • ' 公共方法 - [功能分类]
  • ' 私有方法 - [功能分类]
  • ' 事件处理
  • ' 类事件
  • ' 辅助函数
  • ' 错误处理

四、编码规范

4.1 Option Explicit

强制要求: 所有文件必须包含 Option Explicit

Option Explicit

4.2 注释规范

文件头注释

'=========================================================================
'
' cModbusMaster - Modbus Master/Client Implementation for VB6
'
' Purpose: Provides Modbus RTU and TCP master/client functionality
'          - Read/Write Coils (0x01, 0x02, 0x05, 0x0F)
'          - Read/Write Registers (0x03, 0x04, 0x06, 0x10)
'          - Support for RTU (Serial) and TCP modes
'
' Author: Auto
' Date: 2026-01-16
'
'=========================================================================

函数注释

'读取线圈状态
'@param StartAddress 起始地址
'@param Quantity 读取数量
'@return Boolean数组,True表示ON,False表示OFF
Public Function ReadCoils(ByVal StartAddress As Long, ByVal Quantity As Long) As Boolean()

行内注释

' 初始化默认值
m_Timeout = 60

' 检查是否启用流式响应
If m_Stream = True Then
    ' 流式响应处理
    Call SendStreamRequest
End If

TODO/FIXME 注释

' TODO: 需要添加重连机制
' FIXME: 这里的错误处理不完善

4.3 缩进和空格

缩进: 使用 4 个空格(不使用 Tab)

空格规则:

' 运算符前后加空格
If a > b Then
a = b + c

' 逗号后加空格
Function Test(ByVal a As Long, ByVal b As Long) As Long

' 不要在行尾添加多余空格

换行:

' 参数过多时换行,对齐
Public Function BuildReadRequest(ByVal FC As ModbusMasterFunctionCode, _
                               ByVal StartAddress As Long, _
                               ByVal Quantity As Long) As Byte()

' 条件语句换行
If condition1 And _
   condition2 And _
   condition3 Then

4.4 错误处理

标准错误处理模式

Public Function [MethodName](参数...) As [Type]
    On Error GoTo ErrorHandler

    ' 主要代码

    Exit Function
ErrorHandler:
    RaiseError "[MethodName] failed: " & ERR.Description
End Function

私有错误处理函数

Private Sub RaiseError(ByVal Description As String)
    Debug.Print "[" & MODULE_NAME & "] Error: " & Description
    RaiseEvent OnError(Description)
End Sub

Class_Terminate 安全模式

Private Sub Class_Terminate()
    On Error Resume Next

    ' 清理代码
    Set m_Object1 = Nothing
    Set m_Object2 = Nothing

    On Error GoTo 0
End Sub

4.5 数组处理

数组声明:

' 使用显式下界
Dim baBuffer() As Byte
Dim lValues(0 To 99) As Long

' 重新定义数组
ReDim baBuffer(lSize - 1) As Byte
ReDim Preserve baBuffer(UBound(baBuffer) + 1) As Byte

数组检查:

' 检查数组是否为空
If UBound(baArray) >= 0 Then
    ' 处理数组
End If

' 更安全的检查
If Not (Not baArray) Then
    ReDim baArray(0) As Byte
End If

4.6 集合处理

' 创建集合
If m_Messages Is Nothing Then
    Set m_Messages = New Collection
End If

' 添加项目
Dim Msg As New Scripting.Dictionary
Msg("role") = "user"
Msg("content") = "text"
m_Messages.Add Msg

' 遍历集合
Dim Item As Variant
For Each Item In m_Messages
    ' 处理项目
Next Item

' 清空集合
Set m_Messages = Nothing

4.7 事件处理

定义事件

Public Event OnConnect()
Public Event OnDisconnect()
Public Event OnError(ByVal Description As String)
Public Event OnDataReceived(Data() As Byte)

触发事件

' 触发事件
RaiseEvent OnConnect

' 触发带参数的事件
RaiseEvent OnError("Connection failed", 1001)

事件处理

' WithEvents 对象
Private WithEvents m_TransportTCP As cModbusTransportTCP

' 事件处理程序
Private Sub m_TransportTCP_OnConnect()
    m_State = MB_MASTER_STATE_CONNECTED
    RaiseEvent OnConnect
End Sub

4.8 链式调用

返回 Me 的方法:

Public Function ApiKey(Key As String) As cAI
    m_ApiKey = Key
    Set ApiKey = Me
End Function

Public Function Temperature(Value As Double) As cAI
    m_Temperature = Value
    Set Temperature = Me
End Function

使用方式:

Set AI = New cAI
AI.ApiKey("key123") _
   .BaseUrl("https://api.example.com") _
   .Model("gpt-3.5") _
   .Chat("Hello")

五、特殊模式

5.1 属性赋值前检查

Public Property Let ProtocolType(ByVal Value As ModbusMasterProtocolType)
    If m_State = MB_MASTER_STATE_CONNECTED Then
        RaiseError "Cannot change protocol type while connected"
        Exit Property
    End If
    m_ProtocolType = Value
End Property

5.2 验证函数

Private Sub ValidateQuantity(ByVal Quantity As Long, ByVal MaxQuantity As Long)
    If Quantity < 1 Or Quantity > MaxQuantity Then
        ERR.Raise vbObjectError + 1, "cModbusMaster", "Invalid quantity: " & Quantity
    End If
End Sub

5.3 字符串处理

' 检查空字符串
If LenB(sText) = 0 Then
    ' 空字符串
End If

' 字符串截取
sResult = Left$(sText, 10)
sResult = Mid$(sText, 5, 3)
sResult = Right$(sText, 5)

' 字符串转换
sUpper = UCase$(sText)
sLower = LCase$(sText)
sTrim = Trim$(sText)

' 字符串连接
sResult = sPart1 & sPart2

5.4 API 调用

' 声明 API
Private Declare Sub CopyMemory Lib "kernel32" Alias "RtlMoveMemory" _
    (Destination As Any, Source As Any, ByVal Length As Long)

Private Declare Function GetTickCount Lib "kernel32" () As Long

' 使用 API
CopyMemory baDest(0), baSrc(0), lLength
lTickCount = GetTickCount()

六、最佳实践

6.1 初始化

Private Sub Class_Initialize()
    ' 初始化基础类型
    m_Timeout = 60
    m_Temperature = 1.0

    ' 初始化对象(延迟初始化)
    ' Set m_Messages = New Collection

    ' 初始化状态
    m_State = MB_MASTER_STATE_DISCONNECTED
    m_IsStreaming = False
End Sub

6.2 清理

Private Sub Class_Terminate()
    On Error Resume Next

    ' 断开连接
    If m_State = MB_MASTER_STATE_CONNECTED Then
        Call DisConnect
    End If

    ' 清理对象
    Set m_Object1 = Nothing
    Set m_Object2 = Nothing
    Set m_Collection = Nothing

    ' 清理事件
    If Not m_Timer Is Nothing Then
        m_Timer.Enabled = False
        Set m_Timer = Nothing
    End If

    On Error GoTo 0
End Sub

6.3 类型转换

' 安全的数值转换
lValue = CLng(sValue)
iValue = CInt(sValue)
dblValue = CDbl(sValue)

' 字符串到数组
baBytes = StrConv(sText, vbFromUnicode)
sText = StrConv(baBytes, vbUnicode)

' 类型检查
If VarType(Value) = vbString Then
    ' 处理字符串
End If

6.4 常用函数

' 数组检查函数
Private Function IsArrayEmpty(arr() As Byte) As Boolean
    On Error Resume Next
    IsArrayEmpty = (UBound(arr) < 0)
    On Error GoTo 0
End Function

' 检查对象是否初始化
If Not m_Object Is Nothing Then
    ' 使用对象
End If

' 设置默认值
Function Nz(Value As Variant, Optional Default As Variant = 0) As Variant
    If IsEmpty(Value) Or IsNull(Value) Then
        Nz = Default
    Else
        Nz = Value
    End If
End Function

七、文件组织规则

7.1 目录结构

src/
├── [功能模块]/
│   ├── c[主类].cls          # 主要功能类
│   ├── m[模块].bas          # 公共模块
│   ├── [子功能]/
│   │   ├── c[子类].cls      # 子类
│   │   └── m[模块].bas
│   └── Demos/               # 示例代码
├── StaticClass/             # 静态类
│   ├── cVBMAN.cls           # 主入口类
│   └── sGlobal.cls          # 全局单例
├── Common/                  # 公共定义
└── Tools/                   # 工具类
    ├── Array/
    ├── String/
    └── ...

7.2 文件依赖

  • 类之间尽量保持低耦合
  • 使用接口或公共模块共享数据
  • 避免循环依赖

八、代码审查要点

8.1 必须检查项

8.2 命名检查

8.3 代码质量


九、注意事项

9.1 VB6 特性

  1. 数组索引: VB6 数组默认索引从 0 开始
  2. 字符串: 使用 LenB 检查空字符串更快
  3. 对象引用: 使用 Set 赋值对象,使用 Nothing 释放
  4. 错误处理: On Error Resume Next 要谨慎使用
  5. 类型转换: 显式类型转换比隐式更安全
  6. 文件编码: 所有 VB 文件必须使用 GBK 编码,否则会导致中文乱码
  7. 换行符: 所有 VB 文件必须使用 CRLF (\r\n),与 VB6 IDE 保持一致

9.2 性能优化

  1. 使用 ByVal 传递简单类型,ByRef 传递数组/对象
  2. 避免频繁的字符串连接,使用 StringBuilder 模式
  3. 集合遍历使用 For Each 而非索引
  4. 使用 Long 而非 Integer(32位系统上更快)
  5. 缓存常用属性值,减少访问

9.3 内存管理

  1. 及时释放对象引用 Set obj = Nothing
  2. 在 Class_Terminate 中清理所有资源
  3. 避免循环引用导致内存泄漏
  4. 使用弱引用或显式清理打破循环引用

十、文件编码和换行符规范

10.1 VB 项目文件编码要求

强制要求: 所有 VB6 项目相关文件必须使用 GBK 编码

适用文件类型:

  • .frm - 窗体文件
  • .cls - 类文件
  • .bas - 模块文件
  • .ctl - 控件文件
  • .pag - 属性页文件
  • .dob - 用户文档文件
  • .dsr - 设计器文件
  • .vbp - 项目文件(工程文件)
  • .vbg - 项目组文件
  • .res - 资源文件

原因:

  • VB6 IDE 默认使用 ANSI/GBK 编码
  • 使用 UTF-8 或其他编码可能导致:
    • 中文注释乱码
    • 字符串常量显示异常
    • IDE 加载失败或崩溃

文件保存设置:

  • 使用支持 GBK 的编辑器(如 VSCode、Notepad++ 等)
  • 文件保存时明确指定为 GBK 编码
  • 避免 BOM (Byte Order Mark) 头

10.2 换行符规范

强制要求: 所有 VB6 项目文件必须使用 CRLF 换行符(\r\n)

原因:

  • VB6 IDE 原生运行在 Windows 平台
  • 使用 LF (Unix) 或 CR (Mac) 可能导致:
    • 代码显示异常
    • 版本控制工具差异提示
    • 某些情况下 IDE 无法正确解析

配置示例 (.editorconfig):

[*.{frm,cls,bas,ctl,pag,dob,dsr,vbp,vbg,res}]
charset = gbk
end_of_line = crlf
insert_final_newline = true

10.3 版本控制配置

.gitattributes 配置建议:

*.{frm,cls,bas,ctl,pag,dob,dsr,vbp,vbg,res} text eol=crlf charset=gbk

10.4 验证检查

文件编码检查:

# Linux/Mac: 检查文件编码
file -i filename.cls

# 检查是否为 GBK
file -i filename.cls | grep "gbk"

换行符检查:

# 检查文件行尾
file filename.cls

# Unix/Linux 文件应显示: "ASCII text"
# Windows 文件应显示: "ASCII text, with CRLF line terminators"

VSCode 检查:

  • 右下角状态栏查看编码(应显示为 GBK)
  • 右下角状态栏查看行尾符(应显示为 CRLF)

10.5 常见问题

问题 1: 文件保存后中文乱码

  • 原因: 编辑器使用了 UTF-8 编码
  • 解决: 使用另存为,选择 GBK 编码

问题 2: Git 提示大量文件改动

  • 原因: 换行符不匹配
  • 解决: 运行 git config core.autocrlf true 或手动转换为 CRLF

问题 3: VB6 IDE 加载失败

  • 原因: 文件编码不兼容
  • 解决: 确保所有文件使用 GBK 编码

十一、示例代码

10.1 完整类示例

参见项目中的文件:

  • cModbusMaster.cls - 协议实现类示例
  • cAsyncSocket.cls - 底层封装类示例
  • cAI.cls - 链式调用类示例

10.2 完整模块示例

参见项目中的文件:

  • mModbus.bas - 协议公共模块
  • ToolsArray.bas - 工具函数模块

文档版本: 1.1 最后更新: 2026-01-21 维护者: VBMAN 项目组