Naming

Every time we create an interface, component, base, project or workspace, we need to come up with a good name. Finding good names is one of the hardest and most important thing in software. Every time we fail to find a good name, it will make the system harder to reason about and change.
The components are the core of Polylith, so let's start with them. If a component does one thing then we can name it based on that, e.g. validator, invoicer or purchaser. Sometimes a component operates around a concept that we can name it after, e.g.: account or car. This can be an alternative if the component does more than one thing, but always around that single concept.
If the component's main responsibility is to simplify access to a third-party API, then suffixing it with -api is a good pattern, like myexternalsystem-api. API's that are heavily used like aws can skip the suffix.
If we have two components that share the same interface, e.g. invoicer, where the invoicer component contains the business logic, while the other component only delegates to a service that includes the invoicer component, then we can name the component that does the remote call, invoicer-remote.
If we have found a good name for the component, then it's generally a good idea to keep the same name for the interface, which is also the default behavior when a component is created, e.g.:
poly create component name:invoicer
...which is the same as:
poly create component name:invoicer interface:invoicer
Bases are responsible for exposing a public API and delegating the incoming calls to components. A good way to name them is to start with what they do, followed by the type of the API. If it's a REST API that takes care of invoicing, then we can name it invoicer-rest-api. If it's a lambda function that generates different reports, then report-generator-lambda can be a good name.
Projects (development excluded) represent the deployable artifacts, like services. Those artifacts should, if possible, be named after what they are, like invoicer or report-generator.
Last modified 11mo ago