coding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

General Coding Best Practices

通用编码最佳实践

Overview

概述

This skill provides a set of core principles and practices for software development. Use this when implementing new features, refactoring existing code, or reviewing code to ensure high quality and maintainability.

本技能提供一套软件开发的核心原则与实践方法。在实现新功能、重构现有代码或进行代码评审时使用本技能，以确保代码的高质量与可维护性。

Core Principles

核心原则

DRY (Don't Repeat Yourself): Avoid logic duplication. If you find yourself writing the same code twice, abstract it.
KISS (Keep It Simple, Stupid): Prefer simple, straightforward solutions over complex ones. Avoid over-engineering.
YAGNI (You Ain't Gonna Need It): Don't implement features or abstractions until they are actually needed.
SOLID Principles:
- Single Responsibility: A class/function should have one reason to change.
- Open/Closed: Software entities should be open for extension but closed for modification.
- Liskov Substitution: Subtypes must be substitutable for their base types.
- Interface Segregation: Many client-specific interfaces are better than one general-purpose interface.
- Dependency Inversion: Depend on abstractions, not concretions.

DRY（Don't Repeat Yourself，不要重复自己）： 避免逻辑重复。如果发现自己在重复编写相同代码，请将其抽象封装。
KISS（Keep It Simple, Stupid，保持简单）： 优先选择简单直接的解决方案，而非复杂方案。避免过度设计。
YAGNI（You Ain't Gonna Need It，你不会用到它）： 除非确实需要，否则不要实现功能或进行抽象。
SOLID原则：
- 单一职责：一个类/函数应该只有一个修改的理由。
- 开闭原则：软件实体应对扩展开放，对修改关闭。
- 里氏替换：子类必须能够替代其基类使用。
- 接口隔离：多个面向特定客户端的接口优于一个通用接口。
- 依赖倒置：依赖于抽象，而非具体实现。

Implementation Guidelines

实施指南

Clean Code: Use descriptive names for variables, functions, and classes. Write code that is easy to read and understand.
Small Functions: Keep functions small and focused on a single task.
Error Handling: Use proactive error handling. Validate inputs and handle exceptions gracefully.
Documentation: Document the why, not the what. Use self-documenting code where possible.
Security: Sanitize inputs, avoid hardcoding secrets, and follow the principle of least privilege.
Performance: Be mindful of time and space complexity, but avoid premature optimization.

清晰代码： 为变量、函数和类使用具有描述性的命名。编写易于阅读和理解的代码。
短小函数： 保持函数短小，专注于单一任务。
错误处理： 采用主动式错误处理。验证输入并优雅地处理异常。
文档编写： 记录代码的“为什么”，而非“是什么”。尽可能使用自文档化代码。
安全性： 对输入进行清理，避免硬编码机密信息，遵循最小权限原则。
性能： 关注时间与空间复杂度，但避免过早优化。

Automated Analysis & Quality Control

自动化分析与质量控制

Static Analysis & Linting: Every project MUST have automated linting, formatting and static analysis (e.g., ESLint, Prettier, Ruff, Sonar).
- Check: Identify if these tools are configured.
- Propose: If missing, immediately propose adding them (e.g.,
```
npm install --save-dev eslint
```
  ).
Automated Tests: Ensure there is a test runner configured (e.g., Jest, Pytest).
- Check: Look for
```
tests/
```
  directory or test configurations in
```
package.json
```
  /
```
pyproject.toml
```
  .
- Propose: If missing, propose a testing framework and initial setup.

静态分析与代码检查： 每个项目都必须配置自动化代码检查、格式化与静态分析工具（如ESLint、Prettier、Ruff、Sonar）。
- 检查： 确认这些工具是否已配置。
- 建议： 如果未配置，立即建议添加（例如：
```
npm install --save-dev eslint
```
  ）。
自动化测试： 确保已配置测试运行器（如Jest、Pytest）。
- 检查： 查找
```
tests/
```
  目录或
```
package.json
```
  /
```
pyproject.toml
```
  中的测试配置。
- 建议： 如果未配置，建议选择合适的测试框架并完成初始设置。

Verifying Code Changes

代码变更验证

Before completing any task, you MUST perform the following verification loop:

Simplification: Use the code-simplifier plugin to make the code cleaner and more maintainable.
Self-Code Review:
- Review the changes against the task requirements.
- Ensure compliance with this
```
coding
```
  skill (DRY, KISS, SOLID).
- Check for potential security vulnerabilities or performance regressions.
Static Analysis & Linting:
- Run the project's linting/format commands (e.g.,
```
npm run lint
```
  ,
```
prettier --check .
```
  ).
- Fix all reported issues.
Unit Testing:
- Add Missing Tests: If new logic was added, write concise unit tests covering the happy path and edge cases.
- Run Tests: Execute the test suite (e.g.,
```
npm test
```
  ,
```
pytest
```
  ).
- Verification: Ensure all tests pass. If they fail, fix the implementation or the test.

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

简化： 使用代码简化插件让代码更简洁、更易于维护。
自我代码评审：
- 根据任务需求评审变更内容。
- 确保符合本
```
coding
```
  技能的要求（DRY、KISS、SOLID）。
- 检查潜在的安全漏洞或性能退化问题。
静态分析与代码检查：
- 运行项目的代码检查/格式化命令（例如：
```
npm run lint
```
  、
```
prettier --check .
```
  ）。
- 修复所有报告的问题。
单元测试：
- 补充缺失测试： 如果添加了新逻辑，编写简洁的单元测试覆盖正常流程与边缘情况。
- 运行测试： 执行测试套件（例如：
```
npm test
```
  、
```
pytest
```
  ）。
- 验证： 确保所有测试通过。如果测试失败，修复实现代码或测试用例。

Key Principles

关键原则

Clarity over Cleverness: Write code for humans first, machines second.
Consistency: Follow the established patterns and style of the existing codebase.
Composition over Inheritance: Prefer combining simple objects to build complex ones rather than creating deep inheritance hierarchies.

清晰优先于技巧： 代码首先是写给人看的，其次才是机器。
一致性： 遵循现有代码库已确立的模式与风格。
组合优于继承： 优先通过组合简单对象来构建复杂对象，而非创建深层的继承层次结构。