stdlib之禅

Source: Dev.to

一种关于简洁、模块化、一致性与工匠精神的哲学。

在过去的几年里，stdlib 已经从一小套实用工具成长为一个庞大且高度模块化的 JavaScript 科学计算系统，能够在网页上运行。成千上万关于 API、命名、性能、包边界以及实现策略的小决策共同塑造了项目的特性。随着项目规模的扩大，明确这些底层原则变得愈发重要——无论是对维护者、贡献者，还是对使用者。

stdlib 的禅

这不是风格指南、检查清单或教条。它是经验的提炼——哪些有效，哪些无效，以及随着代码库和社区的成长哪些倾向于可扩展。

禅旨在帮助回答以下问题：

• 这应该是一个新包还是现有包的一部分？
• 这个 API 是否过于通用？
• 我们应该添加另一个选项还是组合现有功能？
• 这种抽象值得吗？

核心原则

• 做一件事，做好它。
• 拥抱彻底的模块化。
• 更倾向于组合而非配置。
• 稳定性是一项特性。
• 让它显而易见且可预测。
• 不要玩技巧。
• 复杂性会致命——将复杂性上移到更高层。
• 如果难以解释，那就是坏主意。
• 如果难以测试，那就是糟糕的设计。
• 故障应易于诊断。
• 价值一致性高于一切（除非正确性、安全性或清晰性另有要求）。
• 像 C 那样编写：明确表达，默认避免多态，倾向于可预测的性能特性。
• 在可扩展的地方自动化；在模糊的地方停止。
• 代码的阅读频率远高于编写频率——对未来的自己好一点。
• 代码是一门工艺——悉心打理。
• 错误具有传染性——及早修复。
• 简单即美。

重复主题

小而独立的包

如果某个东西能够独立存在，就应该让它独立。标准库有意由许多小包组成，而不是少数大型包。这有助于复用、简化测试，并且让使用者只引入他们需要的部分。它也强制了纪律性：每个包必须有明确的目的和边界。

简单的构建块

我们更倾向于使用简单的原语，而不是高度可配置的接口。与其添加更多标志、选项和模式，不如提供可以组合使用的小构建块。这使得各个 API 可预测，避免了组合爆炸的复杂性。

分层的复杂度

底层 API 应该简洁、可预测且易于推理。更复杂的行为——分支逻辑、多模式、编排——应放在基于这些原语之上的更高层实用工具中。这种分离对性能和可维护性都至关重要。

一致的命名与行为

用户不应猜测 API 的作用。项目中命名约定、参数顺序和错误行为保持一致，降低认知负担，使系统更易学习和使用。

可预测的性能

“像 C 那样编写”更多指的是思维方式，而非语言语法。我们偏好单态代码路径、显式行为以及可预测的性能特征。隐藏的分配、过度的多态和隐式工作会带来性能和调试上的挑战。

清晰胜于巧妙

因为代码被阅读的次数远多于编写的次数，禅意强调清晰、简洁，以及不仅解释代码做了什么，更解释为什么这么做的文档。

Zen 的演进

stdlib 的 Zen 并非一成不变。随着项目的演进，我们对什么有效、什么无效的理解也会随之变化。对 Zen 的修改应当是罕见的、深思熟虑的，并且基于实践经验。

如果你正在为 stdlib 做贡献，在设计 API 或审查代码时请以 Zen 为参考。它并不能回答所有问题，但应能帮助你思考权衡，并使决策与项目的整体方向保持一致。

当你犹豫不决时：倾向于简洁、清晰和一致。

结束

stdlib 是一个在 JavaScript 和 Web 上进行科学计算的持续实验，建立在坚实的原则之上。Zen 捕捉了这些原则，使项目能够在保持一致性的同时继续发展。

欢迎提供反馈。如果您喜欢这篇文章，请在 GitHub 上给我们点一个星 🌟，并考虑支持该项目。您的贡献和持续支持有助于确保 stdlib 的长期成功。