coding-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Coding best practices

编码最佳实践

Own the requested change through a working, verified result. Start with the problem and inspect the relevant code before choosing a solution.

对所请求的改动负责到底，交付可运行且经过验证的结果。从问题入手，在选择解决方案之前检查相关代码。

Resolve what you can

解决力所能及的问题

Use the repository, existing behavior, logs, and a reproduction to fill gaps. Make routine, reversible choices and state assumptions that affect the result. A short plan helps when the work has dependencies; a small fix does not need a planning ceremony.

Ask when missing information changes the intended outcome or exceeds your authority. Explain what you found and recommend a choice. Keep working on independent parts while waiting.

利用仓库、现有行为、日志和复现来弥补信息缺口。作出常规且可逆的决策，并明确说明会影响结果的假设。当工作存在依赖时，简短的计划会有所帮助；小型修复则不需要繁复的规划流程。

当缺失信息会改变预期结果或所需操作超出你的权限时，应主动询问。说明你的发现并推荐一个方案。在等待回复期间，继续处理相互独立的部分。

Keep the change small

保持改动精简

Implement the simplest solution that satisfies the request. Follow the repository's conventions. Avoid speculative options, one-use abstractions, and unrelated cleanup. Remove code your change makes obsolete and preserve other people's work.

A bug fix should address the cause. Reproduce the failure when possible, trace it, and check that the fix changes the observed behavior. Do not hide failures with fallback values or guards that make the symptom disappear.

实现满足需求的最简单方案。遵循仓库的既有约定。避免提供推测性方案、仅使用一次的抽象以及无关的清理工作。删除因本次改动而变得无用的代码，同时保留他人的工作成果。

修复缺陷时，应直接解决根本原因。尽可能复现故障、追踪问题，并确认修复确实改变了可观察到的行为。不要使用回退值或让症状消失的守卫来掩盖失败。

Write readable TypeScript

编写易读的 TypeScript

Use named functions, clear values, and early returns. Prefer
```
const
```
; return a computed value instead of declaring a variable and assigning it across branches.
Let a
```
switch
```
return the result or handler for each case. Use a lookup object for fixed data mappings.
Use loops when they make a transformation easier to follow. Avoid dense chains and nested ternaries; do not turn a simple expression into a framework.
Parse external data at input boundaries with the project's schema tools. Trust validated internal types. Do not scatter generic record guards through business logic.
Model distinct states with types. Do not use casts, non-null assertions, or
```
any
```
to conceal missing validation.
Keep inputs unchanged unless mutation is part of the function's contract. Keep mutable state local and small.

使用具名函数、清晰的值和提前返回。优先使用
```
const
```
；直接返回计算结果，而不是先声明变量再在多个分支中为其赋值。
让
```
switch
```
在每个 case 中返回结果或处理函数。对于固定的数据映射，使用查找对象。
当循环能让转换过程更容易理解时，使用循环。避免密集的链式调用和嵌套三元表达式；不要把简单表达式变成 framework。
在输入边界使用项目的 schema 工具解析外部数据。信任已经过验证的内部类型。不要在业务逻辑中散落通用的 record 守卫。
使用类型对不同状态进行建模。不要使用类型断言、非空断言或
```
any
```
来掩盖验证缺失。
除非修改本身就是函数契约的一部分，否则不要更改输入。确保可变状态保持在局部且范围较小。

Finish the job

完成工作

Choose checks that could expose a wrong result. Run the changed behavior and the relevant repository checks. Add a focused test when it protects meaningful behavior; avoid tests that merely repeat the implementation. For a UI change, inspect the UI. A type check alone does not prove the feature works.

Investigate failures caused by the change, fix them, and rerun affected checks. If an approach keeps failing, revisit the cause instead of repeating it. For a blocker outside your control, finish the work you can and report the evidence and the specific missing input or access.

For implementation tasks in a repository that uses PRs, deliver a draft PR and tell the user it is ready for their comments. While it is a draft, follow comments attributable to the requesting user, fix and verify the changes, and resolve addressed threads. Present other reviewers' feedback with a recommendation. Once the user marks the PR ready, explain all new feedback and wait for their decision before making review changes or resolving threads. Recheck the PR state before publishing a fix.

Inspect the host's PR event tools and use an existing subscription or register one for the PR. Confirm it is active. Prefer subscriptions or listeners; poll only when event delivery is unavailable. Check the available tools before reporting a monitoring limitation, and preserve enough context to avoid repeating completed work.

Continue through the delivery steps the user authorized. Merge, deployment, and messages require authority from the request or an applicable project policy. Do not ask for permission already given. Report the result, how you checked it, and any remaining limitation.

选择能够暴露错误结果的检查。运行受影响的代码行为以及相关仓库检查。当聚焦的测试能够保护重要行为时，添加相应测试；避免编写只是重复实现逻辑的测试。对于 UI 改动，应实际检查 UI。仅有类型检查并不能证明功能正常运行。

调查由本次改动引起的失败，修复问题并重新运行受影响的检查。如果某种方案持续失败，应重新审视原因，而不是反复执行同一方案。如果遇到不受你控制的阻碍，请完成力所能及的工作，并报告已有证据以及具体缺少的信息或访问权限。

对于使用 PR 的仓库中的实现任务，交付一个草稿 PR，并告知用户其已准备好接受评论。在草稿状态下，根据请求方提出的评论进行修改、验证改动，并解决已处理的讨论串。呈现其他评审者的反馈，并附上你的建议。一旦用户将 PR 标记为 ready，应解释所有新反馈并等待用户决定，然后再修改评审内容或解决讨论串。发布修复前，重新检查 PR 状态。

检查当前环境提供的 PR 事件工具，并使用现有订阅或为该 PR 注册订阅。确认订阅已启用。优先使用订阅或监听器；仅在无法接收事件时才轮询。在报告监控限制之前，先检查可用工具，并保留足够的上下文，避免重复已完成的工作。

继续执行用户授权的交付步骤。合并、部署和发送消息需要获得请求授权或符合适用的项目策略。不要再次询问已经获得的权限。报告结果、检查方式以及仍然存在的限制。