📚 课程目录第3章 TwinCAT项目代码与工程整理

3. TwinCAT项目代码与工程整理

在TwinCAT项目验收与量产交付阶段，代码与工程整理的质量直接决定后续维护成本、故障定位速度以及多台设备复制部署的一致性。一个在实验室里“能跑”的项目，如果命名混乱、模块边界模糊、库版本漂移、注释与文档脱节，进入量产现场后往往会在第一次程序变更时暴露出严重问题。本节围绕五个相互关联的整理维度展开：命名规范、模块化结构、版本管理、库文件管理、注释与文档同步，并给出可直接落地的组织方式。

命名规范：让对象名本身携带信息

TwinCAT工程中的命名对象包括PLC库、POU（程序、功能块、函数）、变量、结构体、枚举、任务、I/O映射变量以及TwinCAT项目文件。命名规范的目标不是“好看”，而是让工程师在不打开实现代码的情况下，仅凭名称判断对象的类型、层级和用途。

推荐采用“前缀+领域+功能+类型后缀”的组合方式。例如功能块使用 FB_ 前缀，函数使用 F_，程序使用 PRG_，结构体使用 ST_，枚举使用 E_。领域缩写应统一，例如 Axis、Conveyor、Safety、HMI。一个典型的功能块名称为 FB_ConveyorSpeedCtrl，一个结构体为 ST_AxisConfig，一个枚举为 E_MachineState。变量命名建议采用匈牙利式或语义式前缀，如 bEnable、nCounter、rSetSpeed、stAxisCfg、eState，其中 b 表示BOOL，n 表示整数，r 表示REAL，st 表示结构体，e 表示枚举。对于I/O变量，建议在名称中保留物理位置信息，例如 i_bX01_HomeSensor、q_rY03_SpeedRef，便于与电气图纸对照。

命名规范必须形成书面约定并纳入代码评审。仅靠口头约定，在多人协作中通常会在两周内失效。建议将命名规则写入项目根目录的 NAMING_CONVENTION.md，并在TwinCAT项目中通过库或模板POU提供标准命名示例。

模块化结构：按设备层级与功能职责划分

TwinCAT项目的模块化结构应同时反映“设备物理层级”和“软件功能职责”。常见的组织方式是在PLC项目中建立以下文件夹层级：00_System、01_IO、02_Devices、03_Sequences、04_HMI、05_Diagnostics、06_Libraries。其中 00_System 放置任务配置、全局常量、系统状态机；01_IO 放置I/O映射与硬件抽象；02_Devices 按设备类型放置功能块实例，如 FB_Axis、FB_Cylinder、FB_Vacuum；03_Sequences 放置工艺步序；04_HMI 放置与HMI交互的接口变量；05_Diagnostics 放置报警、趋势与诊断逻辑；06_Libraries 放置项目引用的库文件与版本记录。

模块化的关键判断标准是：一个功能块是否可以被独立测试、独立替换、独立复用。如果一个功能块内部直接访问了全局I/O变量，它就很难被复用。推荐做法是功能块只通过输入输出接口与外部交互，I/O映射在 01_IO 层完成。例如 FB_Axis 的输入为 bEnable、rSetPos、rSetVel，输出为 bReady、bBusy、rActPos、nErrorID，而不直接引用 Axis1 的硬件变量。这样在第二台设备上复用时，只需重新实例化并映射I/O即可。

版本管理：从“文件夹副本”升级为可追溯仓库

许多TwinCAT项目在早期采用“项目名_日期_备份”的文件夹方式管理版本，这种方式在单机调试阶段尚可应付，但进入量产交付后无法回答“当前设备上运行的是哪个版本”“这个修改是谁在什么时候引入的”“如何回退到上一个稳定版本”这三个问题。推荐使用Git或SVN建立版本仓库，TwinCAT项目文件（.tsproj、.plcproj、.tpy、.tmc）以及PLC源代码（.TcPOU、.TcDUT、.TcGVL）均应纳入版本控制。

分支策略建议采用 main、dev、hotfix 三条主线。main 分支对应已验收发布的稳定版本，每次量产交付打Tag，例如 v1.0.0-release、v1.1.0-release。dev 分支用于日常开发与集成测试。hotfix 分支用于现场紧急修复，修复完成后合并回 main 和 dev。提交信息应包含模块名与变更类型，例如 fix(FB_Axis): 修复使能后未复位错误码的问题。对于TwinCAT特有的编译产物（如 _Boot 文件夹、.compiled 文件），应通过 .gitignore 排除，避免仓库膨胀。

库文件管理：锁定版本，记录变更

TwinCAT项目通常引用两类库：Beckhoff官方库（如 Tc2_Standard、Tc2_System、Tc3_Motion）和项目自定义库。官方库在TwinCAT版本升级时可能发生行为变化，因此必须在项目文档中记录每个库的版本号。例如在 06_Libraries 文件夹中放置 LIBRARY_MANIFEST.md，记录：库名称、版本号、引用位置、最后更新日期、变更说明。

自定义库应独立成库项目，而不是直接复制POU到每个设备项目中。独立库项目便于统一修改、统一编译、统一发布。库的版本号建议遵循语义化版本：主版本号.次版本号.修订号。当接口不兼容时递增主版本号，当新增功能但保持兼容时递增次版本号，当修复缺陷时递增修订号。每次库发布时，在库项目根目录更新 CHANGELOG.md，记录版本、日期、变更内容、影响范围。

注释与文档同步：让代码自己说明自己

注释与文档同步的核心原则是：注释写在离代码最近的地方，文档写在离交付最近的地方，两者通过版本号关联。POU头部注释应包含：功能描述、输入输出说明、调用前提、典型调用示例、作者、创建日期、最后修改日期、修改人。变量注释应在变量声明行右侧或上方直接说明含义、单位、取值范围。例如：

FUNCTION_BLOCK FB_Axis
(*
    功能：单轴运动控制功能块，封装使能、点动、绝对定位、错误复位
    输入：bEnable(使能), rSetPos(目标位置 mm), rSetVel(目标速度 mm/s)
    输出：bReady(就绪), bBusy(运行中), rActPos(实际位置 mm), nErrorID(错误码)
    前提：轴已配置并映射到NC任务
    示例：fbAxis1(bEnable := bMachineReady, rSetPos := 100.0, rSetVel := 50.0);
*)
VAR_INPUT
    bEnable   : BOOL;   // 使能信号，上升沿启动
    rSetPos   : REAL;   // 目标位置，单位 mm
    rSetVel   : REAL;   // 目标速度，单位 mm/s
END_VAR

文档同步方面，建议在项目根目录维护 README.md（项目概述、环境要求、编译步骤）、CHANGELOG.md（版本变更记录）、NAMING_CONVENTION.md（命名规范）、LIBRARY_MANIFEST.md（库版本清单）。每次代码提交时，检查CHANGELOG是否同步更新。对于量产交付，还应提供 RELEASE_NOTES.md，说明本次交付包含的功能、修复的问题、已知限制、升级注意事项。

整理检查清单（交付前逐项确认）：

所有POU、变量、结构体、枚举均符合命名规范，无 POU_1、Var1 等默认名。
PLC项目文件夹层级完整，功能块不直接访问全局I/O。
代码已提交至版本仓库，main 分支已打Tag，提交信息可读。
LIBRARY_MANIFEST.md 中所有库版本号与实际引用一致。
每个POU头部注释完整，变量注释覆盖单位与取值范围。
CHANGELOG.md 与 RELEASE_NOTES.md 已更新至当前版本。

以上五个维度并非孤立存在。命名规范为模块化提供可读的接口名称，模块化结构为版本管理提供清晰的变更边界，版本管理为库文件管理提供追溯能力，库文件管理为注释与文档同步提供版本锚点。在TwinCAT项目验收与量产交付中，建议将这五项整理工作纳入交付前的固定检查流程，形成可重复、可审计的工程习惯。