Skip to content

NAMING_IMPROVEMENTS.md

Latest commit

 

History

History
187 lines (137 loc) · 6 KB

NAMING_IMPROVEMENTS.md

File metadata and controls

187 lines (137 loc) · 6 KB

LinkerHand C++ SDK 命名规范改进指南

概述

本文档描述了 LinkerHand C++ SDK 的命名规范改进，这些改进旨在提高代码一致性、可维护性和可读性。

改进内容

1. 统一命名空间结构

所有手型号实现类已迁移到统一的 linkerhand::hand 命名空间：

改进前：

namespace LinkerHandL10 {
    class LinkerHand : public linkerhand::hand::IHand { ... };
}

改进后：

namespace linkerhand {
namespace hand {
    class L10Hand : public IHand { ... };
} // namespace hand
} // namespace linkerhand

2. 类名改进

不同型号的手现在使用不同的类名，便于区分：

型号 旧类名 新类名 命名空间
L6/O6 LinkerHandL6::LinkerHand linkerhand::hand::L6Hand linkerhand::hand
L7 LinkerHandL7::LinkerHand linkerhand::hand::L7Hand linkerhand::hand
L10 LinkerHandL10::LinkerHand linkerhand::hand::L10Hand linkerhand::hand
L20 LinkerHandL20::LinkerHand linkerhand::hand::L20Hand linkerhand::hand
L25/L21 LinkerHandL25::LinkerHand linkerhand::hand::L25Hand linkerhand::hand
Modbus L10 ModbusLinkerHandL10::LinkerHand linkerhand::hand::ModbusL10Hand linkerhand::hand

3. 帧属性枚举重命名和改进

各型号的帧属性枚举已重命名，使用更清晰的命名，并改为使用 enum class 以避免命名冲突：

型号 旧枚举名 新枚举名
L6/O6 LinkerHandL6::FRAME_PROPERTY linkerhand::hand::L6FrameProperty
L7 LinkerHandL7::FRAME_PROPERTY linkerhand::hand::L7FrameProperty
L10 LinkerHandL10::FRAME_PROPERTY linkerhand::hand::L10FrameProperty
L20 LinkerHandL20::FRAME_PROPERTY linkerhand::hand::L20FrameProperty
L25/L21 LinkerHandL25::FRAME_PROPERTY linkerhand::hand::L25FrameProperty

重要改进：

  • 枚举类型从 typedef enum 改为 enum class（C++11 强类型枚举）
  • 解决了多个枚举类型之间的命名冲突问题
  • 枚举值现在需要使用作用域限定符访问（如 L6FrameProperty::JOINT_POSITION）

使用示例：

// 旧方式（已废弃，但仍可通过向后兼容别名使用）
LinkerHandL6::FRAME_PROPERTY prop = LinkerHandL6::FRAME_PROPERTY::JOINT_POSITION;

// 新方式（推荐）
linkerhand::hand::L6FrameProperty prop = linkerhand::hand::L6FrameProperty::JOINT_POSITION;

// 转换为整数（用于 CAN 帧）
uint8_t frameProperty = static_cast<uint8_t>(linkerhand::hand::L6FrameProperty::JOINT_POSITION);

4. 参数命名修正

修正了错误的参数命名：

改进前（错误）：

LinkerHandApi(const LINKER_HAND &handJoint, ...);
LINKER_HAND handJoint_;  // 这是手型号，不是关节

改进后（正确）：

LinkerHandApi(const LINKER_HAND &handModel, ...);
LINKER_HAND handModel_;  // 手型号（L6, L7, L10, L20, L21, L25 等）

说明：

  • handJoint 命名不准确，因为这是手型号（Model），不是关节（Joint）
  • 已统一修正为 handModel，更准确地表示手型号

向后兼容性

为了保持向后兼容，所有旧的命名空间和类名都通过 using 别名保留：

// 向后兼容：在旧命名空间中提供别名
namespace LinkerHandL10 {
    using FRAME_PROPERTY = linkerhand::hand::L10FrameProperty;
    using LinkerHand = linkerhand::hand::L10Hand;
} // namespace LinkerHandL10

这意味着现有代码可以继续使用旧的命名，无需立即修改。

使用示例

使用新命名（推荐）

#include "LinkerHandL10.h"
#include "HandFactory.h"

// 使用新的命名空间和类名
using namespace linkerhand;

auto hand = factory::HandFactory::createHand(
    LINKER_HAND::L10,
    HAND_TYPE::RIGHT,
    COMM_CAN_0
);
// hand 的类型是 std::unique_ptr<hand::IHand>
// 实际类型是 hand::L10Hand

使用旧命名（向后兼容）

#include "LinkerHandL10.h"
#include "HandFactory.h"

// 仍然可以使用旧的命名空间
LinkerHandL10::LinkerHand hand(0x27, "can0", 1000000);

迁移建议

阶段一：保持兼容（当前）

  • ✅ 所有新命名已实现
  • ✅ 向后兼容别名已添加
  • ✅ 现有代码无需修改即可继续工作

阶段二：逐步迁移（推荐）

  1. 新代码使用新命名：所有新编写的代码应使用新的命名空间和类名
  2. 更新文档和示例：逐步更新文档和示例代码使用新命名
  3. 代码审查：在代码审查中鼓励使用新命名

阶段三：完全迁移（未来）

在未来版本中，可以考虑：

  • 移除向后兼容别名（需要主版本号升级）
  • 更新所有内部代码使用新命名
  • 更新所有文档和示例

优势

  1. 一致性：所有型号使用统一的命名空间结构
  2. 可读性：类名直接反映型号（L10Hand vs LinkerHand）
  3. 可维护性：统一的命名空间便于管理和查找
  4. 扩展性：新型号可以轻松添加到同一命名空间

注意事项

  1. 工厂类：HandFactory 已更新为使用新类名，但返回类型仍然是 IHand 接口
  2. 头文件：头文件名暂时保持不变，未来可以考虑重命名
  3. 枚举：
    • 帧属性枚举已重命名，枚举值保持不变
    • 枚举类型已改为 enum class，需要使用作用域限定符访问枚举值
    • 这解决了多个枚举类型之间的命名冲突问题（如 JOINT_POSITION、TORQUE_LIMIT 等）
    • 如果需要将枚举值转换为整数，使用 static_cast<uint8_t>()

相关文件

  • include/LinkerHandL6.h - L6/O6 型号实现
  • include/LinkerHandL7.h - L7 型号实现
  • include/LinkerHandL10.h - L10 型号实现
  • include/LinkerHandL20.h - L20 型号实现
  • include/LinkerHandL25.h - L25/L21 型号实现
  • include/ModbusLinkerHandL10.h - Modbus L10 型号实现
  • include/HandFactory.h - 工厂类

版本信息

  • 改进版本：1.1.7+
  • 兼容性：完全向后兼容