Naming Conventions
Consistent terminology in OctoMY™
Naming Conventions
Guidelines for naming things consistently throughout the OctoMY™ codebase.
Pro Tip
When in doubt about what to name something, check the attribute glossary below. Using standard suffixes like
Widget,Activity,Manager, andFactorymakes the codebase easier to navigate. If none of the standard suffixes fit, that's often a sign the class is trying to do too much.
Why naming matters
Naming things in software is surprisingly hard:
- Some things inherently lack a good name, requiring invention
- Names become too long when sufficiently distinguishing from other things
- As projects grow, previously good names overlap with new additions
- Words have multiple meanings (e.g., "Entry" can be "text input" or "item in a list")
Naming principles
-
Find good short descriptive root names - For example:
Address -
Combine with short descriptive attribute names if necessary - For example:
AddressInput -
Add a short descriptive prefix if names overlap - For example:
CarrierAddressvs.NetworkAddress
Guidelines
- There is no shame in selecting a short name without attribute or prefix if possible
- There is no shame in refactoring a name that seemed good at the time
- Refactoring to rename objects is essential for maintaining project quality
Attribute glossary
Standard suffixes used throughout the codebase:
UI components
| Attribute | Description |
|---|---|
Widget |
A reusable GUI widget |
Activity |
A full-screen view (similar to Android activities) |
Input |
A widget for accepting input, such as DecimalInput |
Editor |
A widget for editing an item |
Control |
A widget offering input without being a full editor |
Preview |
A widget displaying a preview of an item |
Selector |
A widget for selecting an item |
Dialog |
A widget shown as a dialog window |
Wizard |
A multi-step guided UI flow |
Data structures
| Attribute | Description |
|---|---|
Entry |
An item in a list (e.g., AddressEntry) - not to be confused with Input |
List |
A list of items with helper methods for management |
Registry |
Like a List but arranged as a dictionary with name lookup |
Model |
A Qt data model subclass for keeping widget data |
Delegate |
A Qt delegate subclass for rendering widgets |
Context |
A collection of related data bundled together |
Type |
An enum describing the type of an item (e.g., CarrierAddressType) |
Lifecycle management
| Attribute | Description |
|---|---|
Manager |
Manages lifecycle for a collection of resources (may be a widget) |
Session |
Manages lifecycle for a single set of resources |
Factory |
Creates items given their specification |
Processing
| Attribute | Description |
|---|---|
Engine |
Central role in performing or coordinating compute/processing |
Processor |
Processes input into output |
Generator |
Produces output |
Renderer |
Draws to a QPainter, usually on behalf of a widget |
Storage
| Attribute | Description |
|---|---|
Loader |
Loads data from storage |
Saver |
Saves data to storage |
Network
| Attribute | Description |
|---|---|
Server |
Background program processing requests from Clients |
Client |
Provides easy access to a Server, hiding implementation details |
Service |
A subclass of Service |
Courier |
A subclass of Courier |
Carrier |
A subclass of Carrier |
Testing
| Attribute | Description |
|---|---|
Tester |
A class used to exercise code (test code only) |
Mock |
A dummy replacement for testing (test code only) |
Utility
| Attribute | Description |
|---|---|
Utils |
Hard-to-categorize helper functions |
Controller |
A subclass of Controller |