diff --git a/docs/architecture/adr/0004-naming-conventions-for-interfaces-and-their-implementations.md b/docs/architecture/adr/0004-naming-conventions-for-interfaces-and-their-implementations.md new file mode 100644 index 00000000000..4f47c9c9c60 --- /dev/null +++ b/docs/architecture/adr/0004-naming-conventions-for-interfaces-and-their-implementations.md @@ -0,0 +1,43 @@ +# Naming Conventions for Interfaces and Their Implementations + +## Status + +- **Accepted** + +## Context + +When there's an interface that has multiple implementations it's often easy enough to give meaningful names to both the +interface and the implementations (e.g. the interface `Backend` with the implementations `ImapBackend` and +`Pop3Backend`). Naming becomes harder when the interface mainly exists to allow having isolated unit tests and the +production code contains exactly one implementation of the interface. +Prior to this ADR we didn't have any naming guidelines and the names varied widely. Often when there was only one +(production) implementation, the class name used one of the prefixes `Default`, `Real`, or `K9`. None of these had any +special meaning and it wasn't clear which one to pick when creating a new interface/class pair. + +## Decision + +We'll be using the following guidelines for naming interfaces and their implementation classes: + +1. **Interface Naming:** Name interfaces as if they were classes, using a clear and descriptive name. Avoid using the + "IInterface" pattern. +2. **Implementation Naming:** Use a prefix that clearly indicates the relationship between the interface and + implementation, such as `DatabaseMessageStore` or `InMemoryMessageStore` for the `MessageStore` interface. +3. **Descriptive Names:** Use descriptive names for interfaces and implementing classes that accurately reflect their + purpose and functionality. +4. **Platform-specific Implementations:** Use the platform name as a prefix for interface implementations specific to + that platform, e.g. `AndroidPowerManager`. +5. **App-specific Implementations:** Use the prefix `K9` for K-9 Mail and `Tb` for Thunderbird when app-specific + implementations are needed, e.g. `K9AppNameProvider` and `TbAppNameProvider`. +6. **Flexibility:** If no brief descriptive name fits and there is only one production implementation, use the prefix + `Default`, like `DefaultImapFolder`. + +## Consequences + +- **Positive Consequences** + + - Improved code readability and maintainability through consistent naming. + - Reduced confusion and misunderstandings by using clear and descriptive names. + +- **Negative Consequences** + + - Initial effort is required to rename existing classes that do not follow these naming conventions.