Keras API design guidelines
These guidelines are meant to help focus design discussions and help us create delightful developer experiences.
These are meant as guidelines, not rules: each decision should be debated in its own unique context.
Some text remixed from external references:
Design end-to-end workflows, not individual functions and classes.
When developing APIs, start by designing end-to-end workflows, and only sketch out specific function/class signatures at the end.
The goal is to arrive to workflows that feel like they are purposefully designed and well-optimized, rather than cobbled together to route around the features provided by the API. The workflows should come first, before atomic features. Features only exist to support a workflow. No feature should exist to provide a capability “just in case”, “because we can”.
Every design review document should prominently feature a code example of one or two end-to-end workflows showing the canonical use-case for the new API.
Every time we discuss choices surrounding a specific API feature, we should start by asking: in what workflows will this be used? Then we should make the choice that makes the most sense with respect to these workflows. We should not make API design decisions about features in isolation.
This implies that we will often ask the question: do users really need to configure this parameter?, and in many cases, the answer will be “no”, rather than being “yes” by default.