Skip to content

Commit 2ffef88

Browse files
liangshaotengliangshaoteng
authored
Merge pull request #3 from soulteary/chore/naming-improvements
chore: project refactor for better maintainability
2 parents 1426733 + 9a0a3f8 commit 2ffef88

14 files changed

+431
-68
lines changed

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,16 @@ auto state_arc = hand.getStateArc();
247247
- 使用示例和注意事项
248248
- 版本兼容性说明
249249
250+
### 命名规范
251+
252+
项目已进行命名规范改进，详细信息请参考：[命名规范改进文档](docs/NAMING_IMPROVEMENTS.md)
253+
254+
主要改进包括：
255+
- 统一命名空间结构（所有型号实现类迁移到 `linkerhand::hand` 命名空间）
256+
- 类名改进（不同型号使用不同类名，如 `L10Hand`, `L20Hand` 等）
257+
- 参数命名修正（`handJoint` → `handModel`）
258+
- 完全向后兼容（旧命名仍可使用）
259+
250260
## 🧪 测试
251261
252262
### 运行测试

‎docs/API-Reference.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,14 +55,14 @@ LinkerHand C++ API 提供了完整的接口用于控制灵心巧手系列灵巧
5555
### LinkerHandApi
5656

5757
```cpp
58-
LinkerHandApi(const LINKER_HAND &handJoint, const HAND_TYPE &handType, const COMM_TYPE commType = COMM_CAN_0);
58+
LinkerHandApi(const LINKER_HAND &handModel, const HAND_TYPE &handType, const COMM_TYPE commType = COMM_CAN_0);
5959
```
6060
6161
**功能描述**
6262
创建并初始化 LinkerHand API 实例。
6363
6464
**参数说明**
65-
- `handJoint` (LINKER_HAND): 机械手型号
65+
- `handModel` (LINKER_HAND): 机械手型号
6666
- 可选值: `LINKER_HAND::O6`, `LINKER_HAND::L6`, `LINKER_HAND::L7`, `LINKER_HAND::L10`, `LINKER_HAND::L20`, `LINKER_HAND::L21`, `LINKER_HAND::L25`
6767
- `handType` (HAND_TYPE): 机械手类型
6868
- `HAND_TYPE::LEFT` - 左手
@@ -623,7 +623,7 @@ void setCurrent(const std::vector<uint8_t> &current);
623623
**使用示例**
624624
```cpp
625625
// 仅 L20 支持
626-
if (hand.handJoint_ == LINKER_HAND::L20) {
626+
if (hand.handModel_ == LINKER_HAND::L20) {
627627
std::vector<uint8_t> current = {100, 100, 100, 100, 100};
628628
hand.setCurrent(current);
629629
}
@@ -655,7 +655,7 @@ void setEnable(const std::vector<uint8_t> &enable = std::vector<uint8_t>(5, 0));
655655
**使用示例**
656656
```cpp
657657
// 仅 L25 支持
658-
if (hand.handJoint_ == LINKER_HAND::L25) {
658+
if (hand.handModel_ == LINKER_HAND::L25) {
659659
std::vector<uint8_t> enable = {1, 1, 1, 1, 1}; // 使能所有手指
660660
hand.setEnable(enable);
661661
}
@@ -687,7 +687,7 @@ void setDisable(const std::vector<uint8_t> &disable = std::vector<uint8_t>(5, 1)
687687
**使用示例**
688688
```cpp
689689
// 仅 L25 支持
690-
if (hand.handJoint_ == LINKER_HAND::L25) {
690+
if (hand.handModel_ == LINKER_HAND::L25) {
691691
std::vector<uint8_t> disable = {1, 1, 1, 1, 1}; // 禁用所有手指
692692
hand.setDisable(disable);
693693
}
@@ -718,7 +718,7 @@ void clearFaultCode(const std::vector<uint8_t> &torque = std::vector<uint8_t>(5,
718718
**使用示例**
719719
```cpp
720720
// 仅 L20 支持
721-
if (hand.handJoint_ == LINKER_HAND::L20) {
721+
if (hand.handModel_ == LINKER_HAND::L20) {
722722
hand.clearFaultCode();
723723
}
724724
```

‎docs/NAMING_IMPROVEMENTS.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# LinkerHand C++ SDK 命名规范改进指南
2+
3+
## 概述
4+
5+
本文档描述了 LinkerHand C++ SDK 的命名规范改进，这些改进旨在提高代码一致性、可维护性和可读性。
6+
7+
## 改进内容
8+
9+
### 1. 统一命名空间结构
10+
11+
所有手型号实现类已迁移到统一的 `linkerhand::hand` 命名空间：
12+
13+
**改进前：**
14+
```cpp
15+
namespace LinkerHandL10 {
16+
class LinkerHand : public linkerhand::hand::IHand { ... };
17+
}
18+
```
19+
20+
**改进后：**
21+
```cpp
22+
namespace linkerhand {
23+
namespace hand {
24+
class L10Hand : public IHand { ... };
25+
} // namespace hand
26+
} // namespace linkerhand
27+
```
28+
29+
### 2. 类名改进
30+
31+
不同型号的手现在使用不同的类名，便于区分：
32+
33+
| 型号 | 旧类名 | 新类名 | 命名空间 |
34+
|------|--------|--------|---------|
35+
| L6/O6 | `LinkerHandL6::LinkerHand` | `linkerhand::hand::L6Hand` | `linkerhand::hand` |
36+
| L7 | `LinkerHandL7::LinkerHand` | `linkerhand::hand::L7Hand` | `linkerhand::hand` |
37+
| L10 | `LinkerHandL10::LinkerHand` | `linkerhand::hand::L10Hand` | `linkerhand::hand` |
38+
| L20 | `LinkerHandL20::LinkerHand` | `linkerhand::hand::L20Hand` | `linkerhand::hand` |
39+
| L25/L21 | `LinkerHandL25::LinkerHand` | `linkerhand::hand::L25Hand` | `linkerhand::hand` |
40+
| Modbus L10 | `ModbusLinkerHandL10::LinkerHand` | `linkerhand::hand::ModbusL10Hand` | `linkerhand::hand` |
41+
42+
### 3. 帧属性枚举重命名和改进
43+
44+
各型号的帧属性枚举已重命名，使用更清晰的命名，并改为使用 `enum class` 以避免命名冲突：
45+
46+
| 型号 | 旧枚举名 | 新枚举名 |
47+
|------|---------|---------|
48+
| L6/O6 | `LinkerHandL6::FRAME_PROPERTY` | `linkerhand::hand::L6FrameProperty` |
49+
| L7 | `LinkerHandL7::FRAME_PROPERTY` | `linkerhand::hand::L7FrameProperty` |
50+
| L10 | `LinkerHandL10::FRAME_PROPERTY` | `linkerhand::hand::L10FrameProperty` |
51+
| L20 | `LinkerHandL20::FRAME_PROPERTY` | `linkerhand::hand::L20FrameProperty` |
52+
| L25/L21 | `LinkerHandL25::FRAME_PROPERTY` | `linkerhand::hand::L25FrameProperty` |
53+
54+
**重要改进**：
55+
- 枚举类型从 `typedef enum` 改为 `enum class`（C++11 强类型枚举）
56+
- 解决了多个枚举类型之间的命名冲突问题
57+
- 枚举值现在需要使用作用域限定符访问（如 `L6FrameProperty::JOINT_POSITION`）
58+
59+
**使用示例**：
60+
```cpp
61+
// 旧方式（已废弃，但仍可通过向后兼容别名使用）
62+
LinkerHandL6::FRAME_PROPERTY prop = LinkerHandL6::FRAME_PROPERTY::JOINT_POSITION;
63+
64+
// 新方式（推荐）
65+
linkerhand::hand::L6FrameProperty prop = linkerhand::hand::L6FrameProperty::JOINT_POSITION;
66+
67+
// 转换为整数（用于 CAN 帧）
68+
uint8_t frameProperty = static_cast<uint8_t>(linkerhand::hand::L6FrameProperty::JOINT_POSITION);
69+
```
70+
71+
### 4. 参数命名修正
72+
73+
修正了错误的参数命名：
74+
75+
**改进前（错误）**：
76+
```cpp
77+
LinkerHandApi(const LINKER_HAND &handJoint, ...);
78+
LINKER_HAND handJoint_; // 这是手型号，不是关节
79+
```
80+
81+
**改进后（正确）**：
82+
```cpp
83+
LinkerHandApi(const LINKER_HAND &handModel, ...);
84+
LINKER_HAND handModel_; // 手型号（L6, L7, L10, L20, L21, L25 等）
85+
```
86+
87+
**说明**：
88+
- `handJoint` 命名不准确，因为这是手型号（Model），不是关节（Joint）
89+
- 已统一修正为 `handModel`，更准确地表示手型号
90+
91+
## 向后兼容性
92+
93+
为了保持向后兼容，所有旧的命名空间和类名都通过 `using` 别名保留：
94+
95+
```cpp
96+
// 向后兼容：在旧命名空间中提供别名
97+
namespace LinkerHandL10 {
98+
using FRAME_PROPERTY = linkerhand::hand::L10FrameProperty;
99+
using LinkerHand = linkerhand::hand::L10Hand;
100+
} // namespace LinkerHandL10
101+
```
102+
103+
这意味着现有代码可以继续使用旧的命名，无需立即修改。
104+
105+
## 使用示例
106+
107+
### 使用新命名（推荐）
108+
109+
```cpp
110+
#include "LinkerHandL10.h"
111+
#include "HandFactory.h"
112+
113+
// 使用新的命名空间和类名
114+
using namespace linkerhand;
115+
116+
auto hand = factory::HandFactory::createHand(
117+
LINKER_HAND::L10,
118+
HAND_TYPE::RIGHT,
119+
COMM_CAN_0
120+
);
121+
// hand 的类型是 std::unique_ptr<hand::IHand>
122+
// 实际类型是 hand::L10Hand
123+
```
124+
125+
### 使用旧命名（向后兼容）
126+
127+
```cpp
128+
#include "LinkerHandL10.h"
129+
#include "HandFactory.h"
130+
131+
// 仍然可以使用旧的命名空间
132+
LinkerHandL10::LinkerHand hand(0x27, "can0", 1000000);
133+
```
134+
135+
## 迁移建议
136+
137+
### 阶段一：保持兼容（当前）
138+
139+
- ✅ 所有新命名已实现
140+
- ✅ 向后兼容别名已添加
141+
- ✅ 现有代码无需修改即可继续工作
142+
143+
### 阶段二：逐步迁移（推荐）
144+
145+
1. **新代码使用新命名**：所有新编写的代码应使用新的命名空间和类名
146+
2. **更新文档和示例**：逐步更新文档和示例代码使用新命名
147+
3. **代码审查**：在代码审查中鼓励使用新命名
148+
149+
### 阶段三：完全迁移（未来）
150+
151+
在未来版本中，可以考虑：
152+
- 移除向后兼容别名（需要主版本号升级）
153+
- 更新所有内部代码使用新命名
154+
- 更新所有文档和示例
155+
156+
## 优势
157+
158+
1. **一致性**：所有型号使用统一的命名空间结构
159+
2. **可读性**：类名直接反映型号（`L10Hand` vs `LinkerHand`）
160+
3. **可维护性**：统一的命名空间便于管理和查找
161+
4. **扩展性**：新型号可以轻松添加到同一命名空间
162+
163+
## 注意事项
164+
165+
1. **工厂类**：`HandFactory` 已更新为使用新类名，但返回类型仍然是 `IHand` 接口
166+
2. **头文件**：头文件名暂时保持不变，未来可以考虑重命名
167+
3. **枚举**：
168+
- 帧属性枚举已重命名，枚举值保持不变
169+
- 枚举类型已改为 `enum class`，需要使用作用域限定符访问枚举值
170+
- 这解决了多个枚举类型之间的命名冲突问题（如 `JOINT_POSITION`、`TORQUE_LIMIT` 等）
171+
- 如果需要将枚举值转换为整数，使用 `static_cast<uint8_t>()`
172+
173+
## 相关文件
174+
175+
- `include/LinkerHandL6.h` - L6/O6 型号实现
176+
- `include/LinkerHandL7.h` - L7 型号实现
177+
- `include/LinkerHandL10.h` - L10 型号实现
178+
- `include/LinkerHandL20.h` - L20 型号实现
179+
- `include/LinkerHandL25.h` - L25/L21 型号实现
180+
- `include/ModbusLinkerHandL10.h` - Modbus L10 型号实现
181+
- `include/HandFactory.h` - 工厂类
182+
183+
## 版本信息
184+
185+
- **改进版本**：1.1.7+
186+
- **兼容性**：完全向后兼容
187+

‎docs/TROUBLESHOOTING.md‎

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,39 @@ undefined reference to `LinkerHandApi::...`
107107

108108
---
109109

110+
### 问题：枚举命名冲突编译错误
111+
112+
**错误信息**:
113+
```
114+
error: 'JOINT_POSITION' conflicts with a previous declaration
115+
error: 'TORQUE_LIMIT' conflicts with a previous declaration
116+
error: 'TOUCH_SENSOR_TYPE' conflicts with a previous declaration
117+
```
118+
119+
**可能原因**:
120+
在旧版本中，多个枚举类型（`L6FrameProperty`、`L7FrameProperty`、`L10FrameProperty` 等）使用 `typedef enum`，导致枚举值泄漏到外层命名空间，当多个头文件同时被包含时会发生命名冲突。
121+
122+
**解决方案**:
123+
此问题已在最新版本中修复。所有枚举类型已改为使用 `enum class`（C++11 强类型枚举），每个枚举值都在自己的作用域内，不会发生命名冲突。
124+
125+
**如果使用旧版本**:
126+
1. 升级到最新版本的 SDK
127+
2. 如果必须使用旧版本，可以：
128+
- 避免同时包含多个型号的头文件
129+
- 使用前向声明和单独编译单元
130+
- 使用命名空间别名隔离不同的枚举类型
131+
132+
**新版本使用方式**:
133+
```cpp
134+
// 使用作用域限定符访问枚举值
135+
linkerhand::hand::L6FrameProperty prop = linkerhand::hand::L6FrameProperty::JOINT_POSITION;
136+
137+
// 转换为整数（用于 CAN 帧）
138+
uint8_t frameProperty = static_cast<uint8_t>(linkerhand::hand::L6FrameProperty::JOINT_POSITION);
139+
```
140+
141+
---
142+
110143
### 问题：CMake 版本过低
111144

112145
**错误信息**:
@@ -398,7 +431,7 @@ CMake 3.5 or higher is required
398431
```cpp
399432
std::vector<uint8_t> pose;
400433

401-
switch (hand.handJoint_) {
434+
switch (hand.handModel_) {
402435
case LINKER_HAND::L6:
403436
case LINKER_HAND::O6:
404437
pose.resize(6);
@@ -423,7 +456,7 @@ CMake 3.5 or higher is required
423456
```cpp
424457
void safeFingerMove(LinkerHandApi& hand, const std::vector<uint8_t>& pose) {
425458
int expected_size = 0;
426-
switch (hand.handJoint_) {
459+
switch (hand.handModel_) {
427460
case LINKER_HAND::L10: expected_size = 10; break;
428461
case LINKER_HAND::L20: expected_size = 20; break;
429462
// ...
@@ -451,7 +484,7 @@ CMake 3.5 or higher is required
451484
1. **检查型号支持**:
452485
```cpp
453486
// 仅 L20 支持 setCurrent
454-
if (hand.handJoint_ == LINKER_HAND::L20) {
487+
if (hand.handModel_ == LINKER_HAND::L20) {
455488
hand.setCurrent(current);
456489
} else {
457490
std::cerr << "警告: setCurrent 仅支持 L20" << std::endl;

‎examples/toolset_example.cpp‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -281,7 +281,7 @@ void interactiveMode(LinkerHandApi &hand)
281281
}
282282
break;
283283
case 11:
284-
if (hand.handJoint_ == LINKER_HAND::L6) {
284+
if (hand.handModel_ == LINKER_HAND::L6) {
285285
std::cout << "L6 - Execute action" << std::endl;
286286

287287
for (size_t i = 0; i < 10; i++) {
@@ -293,7 +293,7 @@ void interactiveMode(LinkerHandApi &hand)
293293
}
294294

295295

296-
} else if (hand.handJoint_ == LINKER_HAND::L7) {
296+
} else if (hand.handModel_ == LINKER_HAND::L7) {
297297
hand.setSpeed(std::vector<uint8_t>(7, HAND_SPEED)); // L7 need 7 speed
298298
hand.setTorque(std::vector<uint8_t>(7, HAND_TORQUE)); // L7 need 7 torque
299299
//---------------------------------------------------------
@@ -309,7 +309,7 @@ void interactiveMode(LinkerHandApi &hand)
309309
std::this_thread::sleep_for(std::chrono::seconds(1));
310310
//---------------------------------------------------------
311311
}
312-
else if (hand.handJoint_ == LINKER_HAND::L10)
312+
else if (hand.handModel_ == LINKER_HAND::L10)
313313
{
314314
hand.setSpeed(std::vector<uint8_t>(5, HAND_SPEED)); // L10 need 5 speed
315315
hand.setTorque(std::vector<uint8_t>(5, HAND_TORQUE)); // L10 need 5 torque
@@ -344,7 +344,7 @@ void interactiveMode(LinkerHandApi &hand)
344344
std::this_thread::sleep_for(std::chrono::seconds(1));
345345
//---------------------------------------------------------
346346
}
347-
else if (hand.handJoint_ == LINKER_HAND::L20)
347+
else if (hand.handModel_ == LINKER_HAND::L20)
348348
{
349349
hand.setSpeed(std::vector<uint8_t>(5, HAND_SPEED)); // L20 need 5 speed
350350
//---------------------------------------------------------
@@ -358,7 +358,7 @@ void interactiveMode(LinkerHandApi &hand)
358358
hand.fingerMove(L20_POSE_OPEN);
359359
std::this_thread::sleep_for(std::chrono::seconds(1));
360360
}
361-
else if (hand.handJoint_ == LINKER_HAND::L25 || hand.handJoint_ == LINKER_HAND::L21)
361+
else if (hand.handModel_ == LINKER_HAND::L25 || hand.handModel_ == LINKER_HAND::L21)
362362
{
363363
hand.setSpeed(std::vector<uint8_t>(25, HAND_SPEED));
364364
hand.setTorque(std::vector<uint8_t>(25, HAND_TORQUE));

0 commit comments

Comments
 (0)