coding

通用编码最佳实践

概述

本技能提供一套软件开发的核心原则和实践。在实现新功能、重构现有代码或审查代码时使用，以确保代码具有高质量且易于维护。

核心原则

• DRY（不要重复自己）： 避免逻辑重复。如果发现自己要重复编写相同的代码，请将其抽象出来。
• KISS（保持简单）： 优先选择简单、直接的解决方案，避免过度设计。
• YAGNI（你不会需要它）： 只有在确实需要时才实现功能或抽象。
• SOLID 原则：
  • 单一职责：一个类或函数应只有一个变更理由。
  • 开闭原则：软件实体应对扩展开放，对修改关闭。
  • 里氏替换原则：子类型必须能够替代其基类型。
  • 接口隔离原则：多个面向客户端的专用接口优于一个通用接口。
  • 依赖倒置原则：依赖抽象，而非具体实现。
• 现有指南： - 遵循项目中的现有指南（例如 CLAUDE.md、AGENT.md 等）。

实现指南

• 整洁代码： 为变量、函数和类使用描述性名称。编写易于阅读和理解的代码。
• 小函数： 保持函数简短，并专注于单一任务。
• 错误处理： 主动处理错误。验证输入，并妥善处理异常。
• 文档： 说明 为什么，而非 是什么。尽可能编写自解释的代码。
• 安全性： 清理输入，避免硬编码密钥，并遵循最小权限原则。
• 性能： 留意时间和空间复杂度，但避免过早优化。

自动化分析与质量控制

• 静态分析与 Lint： 每个项目都必须配置自动化的 Lint、格式化和静态分析工具（例如 ESLint、Prettier、Ruff、Sonar）。
  • 检查： 确认这些工具是否已配置。
  • 提出建议： 如果缺少，请立即建议添加（例如，npm install --save-dev eslint）。
• 自动化测试： 确保已配置测试运行器（例如 Jest、Pytest）。
  • 检查： 查找 tests/ 目录，或 package.json/pyproject.toml 中的测试配置。
  • 提出建议： 如果缺少，请建议测试框架和初始配置。

验证代码更改

完成任何任务之前，都必须执行以下验证流程：

1. 简化： 使用 code-simplifier 插件，让代码更整洁、更易维护。
2. 自我代码审查：
   • 对照任务要求审查更改。
   • 确保符合本 coding 技能（DRY、KISS、SOLID）。
   • 检查潜在的安全漏洞或性能回退。
3. 静态分析与 Lint：
   • 如果项目未配置 Lint/格式化，请建议添加。
   • 运行项目的 Lint/格式化命令（例如，npm run lint、prettier --check .）。
   • 修复所有报告的问题。
4. 单元测试：
   • 如果项目未配置测试运行器，请建议添加。
   • 补充缺失的测试： 如果添加了新逻辑，请编写简洁的单元测试，覆盖正常路径和边界情况。
   • 运行测试： 执行测试套件（例如，npm test、pytest）。
   • 验证： 确保所有测试均通过。如果测试失败，请修复实现或测试。

关键原则

• 清晰胜于取巧： 编写代码时，优先考虑人类读者，其次才是机器。
• 一致性： 遵循现有代码库中已确立的模式和风格。
• 组合优于继承： 优先组合简单对象来构建复杂对象，而不是创建深层继承层次结构。