Zen of stdlib

Source: Dev.to

A philosophy of simplicity, modularity, consistency, and craft.

Over the past several years, stdlib has grown from a small collection of utilities into a large, highly modular system for scientific computing in JavaScript and on the web. Thousands of small decisions about APIs, naming, performance, package boundaries, and implementation strategies have shaped the character of the project. As the project has grown, it’s become increasingly important to make those underlying principles explicit—for maintainers, contributors, and users alike.

The Zen of stdlib

This is not a style guide, a checklist, or a dogma. It is a distillation of experience—what has worked, what hasn’t, and what tends to scale as a codebase and community grow.

The Zen is meant to help answer questions such as:

• Should this be a new package or part of an existing one?
• Is this API too general?
• Should we add another option or compose existing functionality?
• Is this abstraction worth it?

Core Principles

• Do one thing. Do it well.
• Embrace radical modularity.
• Favor composition over configuration.
• Stability is a feature.
• Make it obvious and predictable.
• Don’t be clever.
• Complexity kills – push complexity up the stack.
• If it’s hard to explain, it’s a bad idea.
• If it’s hard to test, it’s a bad design.
• Failure should be easy to diagnose.
• Value consistency above all else (except when correctness, safety, or clarity demands otherwise).
• Write it like C: be explicit, avoid polymorphism by default, and favor predictable performance characteristics.
• Automate where it scales; stop where it obscures.
• Code is read far more often than it is written – be kind to your future self.
• Code is craft – tend to the garden.
• Mistakes are infectious – fix them early.
• Simple is beautiful.

Recurring Themes

Small, Self‑Contained Packages

If something can stand on its own, it should. stdlib is intentionally composed of many small packages rather than a few large ones. This enables reuse, simplifies testing, and allows consumers to include only what they need. It also forces discipline: each package must have a clear purpose and boundary.

Simple Building Blocks

We prefer simple primitives over highly configurable interfaces. Instead of adding more flags, options, and modes, we provide small building blocks that can be composed. This keeps individual APIs predictable and avoids combinatorial complexity.

Layered Complexity

Lower‑level APIs should be simple, predictable, and easy to reason about. More complex behavior—branching logic, multiple modes, orchestration—belongs in higher‑level utilities built on top of those primitives. This separation is critical for both performance and maintainability.

Consistent Naming & Behavior

Users should not have to guess what an API does. Naming conventions, argument ordering, and error behavior are consistent across the project, reducing cognitive load and making the system easier to learn and use.

Predictable Performance

“Write it like C” is less about language syntax and more about mindset. We favor monomorphic code paths, explicit behavior, and predictable performance characteristics. Hidden allocations, excessive polymorphism, and implicit work introduce both performance and debugging challenges.

Clarity Over Cleverness

Because code is read far more often than it is written, the Zen emphasizes clarity, simplicity, and documentation that explains not just what the code does, but why.

Evolution of the Zen

The Zen of stdlib is not fixed. As the project evolves, so will our understanding of what works and what doesn’t. Changes to the Zen should be rare, deliberate, and grounded in experience.

If you’re contributing to stdlib, use the Zen as a reference point when designing APIs or reviewing code. It won’t answer every question, but it should help you reason about trade‑offs and align decisions with the broader direction of the project.

When in doubt: prefer simplicity, clarity, and consistency.

Closing

stdlib is an ongoing experiment in scientific computing with JavaScript and the web, built around strong principles. The Zen captures those principles so the project can continue to grow without losing coherence.

Feedback is welcome. If you’ve enjoyed this post, please give us a star 🌟 on GitHub and consider supporting the project. Your contributions and continued support help ensure the long‑term success of stdlib.