simple-engineering
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSimple Engineering
简单工程
Keep it simple and elegant
保持简单与优雅
Overengineering is a shameful and foolish act, and it is important to always pursue simple and elegant solutions.
Before implementing a feature or fixing a bug, consider all options. Instead of just listing similar choices or being bound by preconceptions and previous thinking, consider all options, including completely different approaches. Among the available options, choose the one that is the clearest, simplest, requires the fewest lines of code, and meets the user's requirements. There is no need to use iron plates and nails to repair torn clothes. Choose a right-sized, simple approach rather than an overly large and complex one.
Also avoid bringing unnecessary complexity into your code. Carefully examine related processing to ensure there are no impossible conditional branches or unnecessary try-catch blocks. Check the type definitions and actual processing, and remove any impossible conditional branches. There is no need to wrap code in a new try-catch block if an exception is unlikely to occur normally or if a try-catch already exists inside the called function.
Flag excessive validation, overly defensive implementation, unnecessary intermediate representation, and unnecessary complexity that does not serve the code's intended purpose. For example, a function that opens product links for a specific website may only need to verify the hostname. Checking the pathname may add complexity without improving security. You might remove validation by defining the function argument as a type such as , or by accepting only a product ID and constructing the link inside the function. These are examples, but you should look for simpler implementations of the same kind. Ask what purpose the code serves and whether the implementation contains only what that purpose requires.
https://example.com/product/{string}过度设计是一种可耻且愚蠢的行为,因此始终应追求简单而优雅的解决方案。
在实现某项功能或修复 bug 之前,请考虑所有可行方案。不要只是罗列相似的选项,也不要受先入为主的观念和既有思维束缚;应考虑所有方案,包括完全不同的方法。在可选方案中,选择最清晰、最简单、所需代码行数最少且满足用户要求的方案。不必用铁板和钉子来修补破衣服。应选择规模合适且简单的方法,而不是庞大而复杂的方法。
同时,避免将不必要的复杂性引入代码。仔细检查相关处理逻辑,确保不存在不可能发生的条件分支或不必要的 try-catch 块。检查类型定义和实际处理逻辑,并移除不可能发生的条件分支。如果异常通常不太可能发生,或者被调用函数内部已经存在 try-catch,则无需再给代码包上一层新的 try-catch 块。
应识别并移除过度验证、过度防御的实现、不必要的中间表示,以及无助于实现代码预期目的的复杂逻辑。例如,一个用于打开特定网站商品链接的函数,可能只需要验证 hostname。检查 pathname 只会增加复杂性,却未必能提升安全性。你可以将函数参数定义为 之类的类型来移除验证,也可以只接受 product ID,并在函数内部构造链接。这些只是示例,但你应寻找同类问题的更简单实现。始终追问代码的目的,并确认实现中只包含实现该目的所必需的内容。
https://example.com/product/{string}Avoid reinventing the wheel
避免重复造轮子
Reinventing the wheel should be avoided. Before adding code, check whether existing code in the project or the project's dependencies already provide functionality that covers part or all of that processing. When implementing complex processing, investigate whether a popular and well-maintained library that achieves equivalent functionality exists, and if so, propose using it to the user.
应避免重复造轮子。在添加代码之前,先检查项目中现有的代码或项目依赖是否已经提供了涵盖部分或全部相关处理逻辑的功能。在实现复杂处理逻辑时,应调查是否存在能够实现同等功能的热门且维护良好的库;如果存在,应向用户提议使用该库。
Keep only necessary changes
仅保留必要的变更
Keep the YAGNI (You aren't gonna need it) principle in mind. You should not introduce complexity just because you might need it in the future. Also, there is no need to maintain backward compatibility for unreleased features.
The code ultimately delivered to the user should be such that every line of change is necessary and no unnecessary code remains. Carefully review the diff line by line, rather than file by file, to ensure that all changes are truly necessary.
请始终牢记 YAGNI(You aren't gonna need it)原则。不要仅仅因为未来可能需要某项功能,就引入不必要的复杂性。此外,对于尚未发布的特性,没有必要维护向后兼容性。
最终交付给用户的代码中,每一行变更都应确有必要,且不应残留任何不必要的代码。应逐行仔细审查 diff,而不是逐个文件审查,以确保所有变更都是真正必需的。
Keep the codebase clean
保持代码库整洁
Writing code is not synonymous with simply adding to existing code. Remove code that is no longer needed. Avoid forcibly adding to existing code that is semantically different; maintain clean code by splitting code as needed and refactoring, including redesigning the code.
Refactoring should not be done only at special times; if there are poorly designed areas within the scope of the current changes that can be resolved with small-scale refactoring during normal work, refactoring should be proactively performed. However, explicit permission from the user should be sought before performing large-scale refactoring.
编写代码并不等同于简单地往现有代码中追加内容。应删除不再需要的代码。避免强行将语义不同的内容加入现有代码;必要时通过拆分代码和重构(包括重新设计代码)来保持代码整洁。
重构不应只在特定时机进行。如果当前变更范围内存在设计不佳的部分,并且可以在日常工作中通过小规模重构解决,就应主动进行重构。但是,在进行大规模重构之前,必须获得用户的明确许可。
DRY principle and modifiability
DRY 原则与可修改性
Keep the DRY principle and modifiability in mind. Avoid defining the same thing repeatedly; instead, aim for code that is easy to modify, where changing a single location automatically updates all related processes. For instance, regarding i18n, the ideal approach is to manage available languages and their labels in one place, such that adding or removing a language requires only updating that single location and adding or removing the corresponding translation file.
请始终牢记 DRY 原则和可修改性。避免重复定义同一事物;应让代码易于修改,使修改单一位置后,所有相关处理逻辑都能自动更新。例如,对于 i18n,理想做法是在一个位置集中管理可用语言及其标签,这样新增或删除语言时,只需更新这一处,并添加或删除相应的 translation file。
Establish a shared understanding
建立共识
If tool is available, actively use it when asking the user questions, especially while running the grilling session. Do not use it for a single yes/no question; instead, use it when asking multiple questions at once or when presenting multiple options. The tool description specifies limiting the number of questions to between one and three, but this is not a functional constraint. If you have more than four questions, enter all of them in , without limiting yourself to three or fewer.
request_user_inputrequest_user_input如果 工具可用,在向用户提问时应主动使用,尤其是在进行 grilling session 时。不要使用它来询问单个是/否问题;应在一次提出多个问题或展示多个选项时使用。工具说明规定将问题数量限制在一到三个之间,但这并非功能层面的约束。如果问题超过四个,请在 中输入全部问题,不要将自己限制为不超过三个。
request_user_inputrequest_user_input