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 特性
- 数组索引: VB6 数组默认索引从 0 开始
- 字符串: 使用
LenB检查空字符串更快 - 对象引用: 使用
Set赋值对象,使用Nothing释放 - 错误处理:
On Error Resume Next要谨慎使用 - 类型转换: 显式类型转换比隐式更安全
- 文件编码: 所有 VB 文件必须使用 GBK 编码,否则会导致中文乱码
- 换行符: 所有 VB 文件必须使用 CRLF (
\r\n),与 VB6 IDE 保持一致
9.2 性能优化
- 使用
ByVal传递简单类型,ByRef传递数组/对象 - 避免频繁的字符串连接,使用
StringBuilder模式 - 集合遍历使用
For Each而非索引 - 使用
Long而非Integer(32位系统上更快) - 缓存常用属性值,减少访问
9.3 内存管理
- 及时释放对象引用
Set obj = Nothing - 在
Class_Terminate中清理所有资源 - 避免循环引用导致内存泄漏
- 使用弱引用或显式清理打破循环引用
十、文件编码和换行符规范
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 项目组