Stp2Glb/.serena/memories/development_guidelines.md

开发指南和最佳实践

开发原则

1. 渐进迭代: 小步快跑，每次提交保持稳定
2. 稳定优先: 不破坏现有功能
3. 学习复用: 研究现有代码模式，保持一致性
4. 架构先行: 设计后实现，确保可维护性

技术栈理解

• Core: C++20, CMake, Pixi包管理
• CAD处理: OpenCASCADE (OCCT) 7.8.1
• 几何算法: CGAL 5.6.1
• 文件格式: STEP输入, GLB输出
• 并行处理: TBB库
• JSON: nlohmann_json
• CLI: CLI11库

开发工作流

1. 环境准备: pixi install && pixi shell
2. 理解需求: 分析要实现的功能
3. 研究现有代码: 查看相似功能的实现
4. 小步实现: 增量开发，频繁测试
5. 质量验证: 编译、测试、手动验证
6. 文档更新: 必要时更新README和注释

架构约束

• 不修改现有接口: 除非绝对必要
• 向后兼容: 新功能不能破坏现有功能
• 模块化: 保持清晰的模块边界
• 错误处理: 使用C++异常机制

性能考虑

• 大文件处理: 注意内存使用
• 并行处理: 合理使用TBB
• 几何计算: 优化OCCT和CGAL的使用
• I/O操作: 高效的文件读写

调试技巧

• 使用调试模式: --debug 参数获取详细信息
• 分步测试: 从小文件开始测试
• 性能分析: 使用计时器测量关键操作
• 内存检查: 注意OpenCASCADE对象的生命周期

常见陷阱

• 路径处理: Windows路径分隔符问题
• 字符编码: 文件名和路径的编码处理
• 内存管理: OCCT对象的智能指针使用
• 线程安全: 并行处理时的数据竞争

代码审查要点

• 是否遵循现有命名约定
• 错误处理是否完整
• 是否有潜在的内存泄漏
• 性能是否符合预期
• 测试覆盖是否充分