Skip to content

0053: Code Names for Internal Products and Services

STATUS

Declined

CONTEXT

The Problem: When Descriptive Names Stop Being Descriptive

Our current approach to naming internal products, services, and repositories relies on descriptive or technical terms that seemed clear at creation but have created ongoing confusion and technical debt. As our engineering organization has grown, these naming conventions have revealed significant limitations that impact communication, architecture decisions, and long-term maintainability.

Current Naming Problems

We face multiple categories of naming issues across our codebase:

Temporal Drift

new_dashboard - Originally created as the "new" dashboard, this repository is now our old, tech-debt laden, problematic system. The name suggests modernity and currency, but the reality is precisely the opposite. We're stuck with either a misleading name or the disruptive cost of renaming.

Communication Ambiguity

  • When someone mentions "Offerwall" in a meeting, are they referring to the api repository or offerwall-ui? This ambiguity wastes time in every discussion requiring clarification.
  • We have a repository simply called api - but calling something api is no more clarifying than calling it mars. Both require context to understand what they actually do. At least mars won't conflict with every other generic API in the organization.

Generic Confusion

shared-services versus common - Even internally, the difference between these repositories is unclear. Generic descriptive names haven't provided the clarity they promised.

Replacement Cycles

ad-tracking is being replaced by Player API - we're continuing the same descriptive naming pattern that created problems in the first place, setting ourselves up for future issues.

Architectural Coupling

targeted-api is named to reflect that it's built on top of offer-api and uses player-api. While not as problematic as other examples, this couples the name to implementation details. If we refactor the architecture, the name becomes misleading.

Scope Creep

airflow-dags actually contains Airflow DAGs, dbt transformation code, and Liquibase migration changelogs. The name only describes one-third of the repository's contents. Renaming to airflow-dags-dbt-liquibase would be unwieldy and would grow worse with each addition.

The False Promise of "Descriptive" Names

The common assumption is that technical or descriptive names are inherently clearer than code names. Our experience demonstrates this is false. Names like api, common, and shared-services provide no more clarity than apollo or mercury would - both require context and documentation to understand. The difference is that code names don't become misleading as systems evolve.

Executive Support

This proposal has support from both CFO Kevin Fox and CEO Brian Fox, who recognize significant benefits to naming internal tech products, including:

  • Increased team ownership: Shifts mindset from "the vendor is doing this to us" to "we are working on Project [Name]"
  • Improved communication: Provides simple, understandable reference points for internal discussions
  • Clearer strategic vision: Helps employees feel more invested in the project's success
  • Boosted team morale: Creates excitement and sense of belonging around shared purpose
  • Strategic clarity: Organizes internal tech portfolio and makes it easier to understand how each product fits into larger company strategy
  • Internal brand building: Reinforces company values and provides long-term business assets

Industry Context

Code names for internal products are industry-standard practice among leading technology companies. AWS (Lambda, Aurora, Athena), Google (Android dessert names, Project Loon), Microsoft (Longhorn, Whistler), and Apple (Purple, Gizmo) all use code names because they solve real engineering problems around system evolution, security, team communication, and long-term maintainability.

This ADR demonstrates that code naming isn't merely a "nice to have" cultural initiative, but a technical decision with measurable impact on productivity, communication efficiency, and technical debt reduction.

CONSIDERED OPTIONS

Implement code names for major products and services across the organization, using a themed naming convention selected by engineering teams.

Scope: Major products only - significant platforms, APIs, and services that are referenced regularly across teams. Not every utility script or minor microservice.

Implementation: Engineers choose names from agreed-upon themes (not marketing or management), maintain a simple naming registry, and document clear guidelines for internal versus external usage.

Option 2: Continue with Descriptive/Technical Names (STATUS QUO)

Maintain current approach of using descriptive or technical names for repositories, services, and products.

Result: Continue experiencing the problems documented above - temporal drift, communication ambiguity, scope creep, architectural coupling, and misleading names.

Option 3: Hybrid Approach

Use code names internally for team communication and development, but maintain descriptive names for external communication, documentation, and customer-facing contexts.

Complexity: Requires maintaining parallel naming systems and clear translation guidelines. May create confusion about which name to use in which context.

DECISION DRIVERS

Strategic Benefits

Competitive Security

  • Leak detection: Apple uses different code names with external suppliers versus internal teams, enabling instant identification of leak sources if certain names appear online
  • Competitor obfuscation: Discussing projects in semi-public spaces (conferences, social media) without revealing strategic direction
  • Confidentiality: "Fight Club" approach - easier to maintain secrecy around sensitive projects

Organizational Flexibility

  • Business pivots: Names remain valid during strategic shifts, product repositioning, or market changes
  • Mergers and acquisitions: Code names create separation between engineering identity and business branding
  • Rebranding: Marketing can rebrand customer-facing names without requiring engineering changes

Risk Mitigation

  • Prevents costly refactoring: No repository renames, URL changes, or dependency updates as systems evolve
  • Reduces technical debt: Decouples system identity from implementation properties
  • Long-term maintainability: Names that stay accurate regardless of underlying technology changes

Developer Recruitment and Retention

  • Engineers value working on named projects with distinct identity
  • Builds emotional attachment to products
  • Creates internal mythology and team culture around projects
  • Makes engineering work feel more meaningful and engaging

Industry Validation

  • AWS, Google, Microsoft, and Apple independently converged on this practice
  • Not a fad - proven approach at scale over decades
  • Demonstrates engineering maturity and best practices

Technical Benefits

Abstraction Layer

  • Decouples identity from properties: A server named "Apollo" remains valid whether it runs Windows or Linux, Node.js or Python, monolith or microservices
  • Prevents the "windows7_64" problem: Function-based names become misleading after upgrades, migrations, or refactoring
  • Accommodates evolution: As quoted from Artsy Engineering, "Projects don't always match their original scope. A system named artsy-admin becomes problematic when administrative utilities split apart."

Refactoring Flexibility

  • Change implementation without changing references across codebase
  • Extract microservices from monoliths without renaming cascades
  • Migrate technologies (databases, frameworks, languages) while maintaining system identity
  • Support gradual transitions and incremental architecture changes

Cognitive Efficiency

  • Memory: Engineers remember "Apollo" or "Gandalf" better than "lon-web-lin-1" or other technical strings
  • Communication: Faster to say and type single-word names in Slack, tickets, documentation
  • Mental models: Easier to reason about systems with distinct, memorable identities
  • Onboarding: New engineers build mental maps faster with distinctive names

Prevents Architectural Bias

  • From Artsy Engineering: "Project names overlapping with domain concepts (like search or images) can predispose teams toward certain architectural decisions. Neutral code names encourage decisions based on architectural and organizational merits instead."
  • Avoids constraining future decisions based on historical naming
  • Enables architecture evolution based on technical merit rather than naming consistency

Supports Microservices and Modularity

  • Named systems are easier to extract into separate services
  • Enables independent evolution of components
  • Facilitates gradual transition from monolith to microservices
  • Creates clear boundaries and ownership

Version Management

  • Reduces mental overhead of constantly changing version numbers during development
  • Makes it easier to assign proper version numbers later
  • Avoids time-consuming changes due to build system constraints and VCS branch renames
  • Separates development identity from release versioning

Code Quality and Maintainability

  • Eliminating naming inconsistencies makes knowledge transfer easier
  • Supports refactoring best practices (removing duplicate code, renaming nondescriptive variables)
  • Creates clear abstraction that enables independent evolution
  • Reduces coupling between system identity and implementation details

Cultural and Communication Benefits

Team Ownership and Engagement

  • From CFO analysis: "Gives a product a name makes it feel like the company's own project, encouraging a sense of ownership"
  • Shifts mindset from passive recipients to active builders
  • Engineers feel more invested in the project's success

Morale and Motivation

  • From Artsy: "It's more engaging to announce that 'Torque is in the wild' than 'data-sync has been deployed'"
  • Code names develop mythologies and personalities within teams
  • Naming rituals and theme selection become team bonding activities
  • Makes mundane activities feel more meaningful

Communication Clarity

  • Resolves current ambiguities (Offerwall, api, shared-services vs common)
  • Provides simple, understandable reference points
  • Reduces time wasted on clarification in meetings and discussions
  • Single-word efficiency in Slack, tickets, and documentation

Strategic Clarity

  • Organizes internal tech portfolio with memorable names
  • Makes it easier to understand how each product fits into larger strategy
  • Helps communicate product relationships and dependencies
  • Creates shared vocabulary across engineering and business teams

Internal Brand Building

  • Reinforces company values and engineering culture
  • Creates cultural artifacts documenting engineering environment
  • Builds emotional attachment to products
  • Provides long-term assets as organization grows

INDUSTRY PRECEDENTS AND RESEARCH

AWS: Measurable Competitive Advantage

Examples

Lambda (serverless compute), Aurora (managed database), Athena (analytics), Redshift (data warehouse)

Research Findings (from IT Pro Today analysis): - AWS's unique terminology makes developers "feel like they're part of a unique constituency of forward-thinking technology practitioners" - Evocative names help services "stand apart and be more memorable" compared to competitors - Lambda is perceived as more innovative than functionally identical competitors (Azure Functions, Google Cloud Functions) - Research shows AWS's naming strategy has "a positive effect on developer relations and community-building"

Lesson Learned: The most successful AWS names (Lambda, Aurora, Athena) are completely tech-agnostic and evocative. Less successful names (Fargate, Greengrass, Sumerian) are opaque without being memorable - "nobody who isn't directly working with them remembers what [they do]."

Key Insight: Distinctive, memorable names that are disconnected from implementation details contribute to competitive advantage by creating perception of innovation and building developer community engagement.

Google: Internal Value After Public Discontinuation

Examples

  • Android dessert names: Quince Tart, Red Velvet Cake, Snow Cone, Tiramisu, Upside Down Cake, Vanilla Ice Cream, Baklava
  • Project Loon (internet via balloons), Project Glass (AR headset)

Critical Decision: Google discontinued public use of Android dessert names starting with Android 10 due to: - Global accessibility issues (dessert names not universally understood) - Cultural localization challenges (terms like "nougat" difficult in certain regions)

But: Google continued using dessert names internally for "repositories, technical documentation, and team coordination"

Key Insight: Google found code names valuable enough for engineering purposes that they retained them internally even after dropping public use. This demonstrates that engineering benefits exist independently of marketing benefits.

Real-World Impact: Project Loon successfully deployed emergency connectivity to Puerto Rico (hurricane) and Peru (flooding), and launched world's first internet-via-balloon service in Kenya. The ambitious "crazy" name helped communicate vision internally.

Microsoft: Thematic Continuity

Examples

  • Chicago (Windows 95): Named for early demo location
  • Longhorn (Windows Vista): Named after Longhorn Saloon between Whistler and Blackcomb mountains
  • Whistler (Windows XP): Ski resort theme
  • O'Hare (Internet Explorer 1): Named for Chicago airport as "point of departure to distant places"

Pattern: Microsoft uses thematic continuity (ski resorts, geographic locations) where related geography suggests version relationships and project connections.

Key Insight: Systematic themes create implicit relationships between products and versions, helping teams understand product families and evolution.

Apple: Security Through Code Names

Examples

Purple (iPhone), Gizmo (Apple Watch), Pink (object-oriented Mac OS features)

Security Strategy

  • "Fight Club" approach: "First Rule of Purple Project is Not Talk About Purple Project"
  • Different code names for external suppliers versus internal teams
  • Instant leak detection: "You'd know instantly who the culprit was if a certain code name started being bandied around online"

Key Insight: Code names provide measurable security benefits through leak detection and enabling discussion of confidential projects in semi-public spaces.

Artsy Engineering: Published Technical Rationale

Artsy Engineering publicly documented their rationale for physics-themed code names:

System Evolution and Flexibility

"Projects don't always match their original scope. A system named artsy-admin becomes problematic when administrative utilities split apart. Code names provide flexibility as systems expand and change purpose without requiring repository renames."

Prevents Architectural Bias

"Project names overlapping with domain concepts (like search or images) can predispose teams toward certain architectural decisions. Neutral code names encourage decisions based on architectural and organizational merits instead."

Accommodates Business Changes

"Branding shifts, products pivot, and companies merge. Code names create separation between internal engineering labels and external user-facing branding, reducing confusion during organizational transitions."

Team Engagement

"It's more engaging to announce that 'Torque is in the wild' than 'data-sync has been deployed.' Code names develop mythologies and personalities within the team and organization over time."

Key Insight: Artsy documented specific engineering benefits from first-hand experience, validating that code names solve real technical problems, not just cultural preferences.

Rands in Repose: Engineering Leadership Best Practices

Rands (Michael Lopp), VP of Engineering at multiple Silicon Valley companies, published "The Codename Rules":

Engineers Choose Codenames

"Engineers building the product should select the codename, not marketing. This ensures the name reflects product development reality rather than marketing strategy."

Emergent, Not Committee-Selected

"The best codenames are emergent and never picked by a committee. Quality names surface organically through team conversation."

Multi-Layered Meaning

"Strong codenames tell the product's story. The example 'Snowball' conveyed both the project's odds and the lead engineer's architectural strengths—capturing both challenge and capability."

Single Word Only

"Efficiency in communication requires single-word names. Multi-word names reduce the cultural significance and communication benefits."

Key Insight: Engineering leadership perspective emphasizes that code names are cultural artifacts that should emerge from engineering teams, not imposed by management.

PROS AND CONS ANALYSIS

Pros (Research-Backed)

System Evolution and Flexibility

  • Names remain accurate as scope, technology, and architecture change
  • Solves our airflow-dags problem (now contains dbt + Liquibase too)
  • Prevents new_dashboard temporal drift issue
  • Enables pivots and strategic changes without technical debt

Prevents Costly Refactoring

  • No repository renames required as systems evolve
  • No URL changes or dependency updates
  • Decouples system identity from implementation properties
  • Reduces cascade effects of architectural changes

Communication Clarity

  • Eliminates ambiguity (resolves "Offerwall", api, shared-services vs common confusion)
  • Single-word efficiency in Slack, tickets, documentation
  • Faster verbal communication in meetings
  • Clear reference points for cross-team discussions

Cognitive Efficiency

  • Engineers remember "Apollo" better than "lon-web-lin-1"
  • Builds clearer mental models of system relationships
  • Faster onboarding for new team members
  • Reduces cognitive load in daily work

Architectural Flexibility

  • Neutral names prevent bias toward specific implementations
  • Addresses targeted-api architectural coupling issue
  • Enables decisions based on technical merit rather than naming consistency
  • Supports gradual refactoring and microservices extraction

Enhanced Security

  • Leak detection capability (Apple strategy)
  • Competitor obfuscation in public discussions
  • Easier to maintain confidentiality around sensitive projects
  • Enables semi-public discussion without revealing strategy

Team Culture and Engagement

  • Fosters ownership and emotional investment
  • Boosts morale through project identity
  • Creates team bonding around naming and mythology
  • Makes engineering work feel more meaningful

Industry Standard Practice

  • Validated by AWS, Google, Microsoft, Apple
  • Demonstrates engineering maturity
  • Proven approach at scale over decades
  • Best practice in leading technology organizations

Long-Term Maintainability

  • Supports trunk-based development and continuous refactoring
  • Enables independent evolution of services
  • Facilitates knowledge transfer and documentation
  • Reduces technical debt accumulation

Cons (With Mitigations)

Learning Curve for New Team Members

  • New engineers must learn what code names mean
  • Requires documentation and onboarding materials
  • Mitigation: Maintain simple naming registry (spreadsheet or doc page) mapping code names to descriptions, technical repos, and team owners. Include in onboarding materials.

Potential Confusion if Poorly Implemented

  • Random, inconsistent names create more confusion than they solve
  • Obscure names without context are problematic (AWS Fargate example)
  • Mitigation: Follow industry best practices - single-word names from agreed-upon themes, engineers choose names, maintain naming registry, avoid completely opaque terms.

Naming Registry Maintenance

  • Requires ongoing maintenance of code name mappings
  • Additional documentation overhead
  • Mitigation: Simple spreadsheet or documentation page is sufficient. Low maintenance overhead compared to benefits. Assign ownership to platform/infrastructure team.

External Communication Complexity

  • Potential confusion in customer/partner communication
  • Sales and support teams need to translate between code names and business terms
  • Mitigation: Clear guidelines for internal vs external usage (see External Sharing Guidelines section). Default to internal-only with explicit exceptions.

Initial Training Investment

  • Time required to communicate new approach
  • Updating existing documentation
  • Mitigation: Phased rollout starting with 3-5 major products minimizes disruption. Training is one-time cost with ongoing benefits.

Net Assessment

The cons are primarily one-time costs (initial training, documentation) or manageable ongoing maintenance (naming registry). The pros deliver continuous value through reduced technical debt, improved communication, architectural flexibility, and team engagement. Industry precedents demonstrate these benefits are real and measurable at scale.

EXTERNAL SHARING GUIDELINES

Recommendation: Primarily Internal, Selective External Use

Based on industry research and best practices, we recommend using code names primarily for internal communication, with selective external use where beneficial.

Default: Internal Only (Google Approach)

Use code names for: - Internal technical documentation - Repository names and namespaces - Team communication (Slack, meetings, tickets) - Architecture diagrams and technical specs - Development and staging environments - Internal dashboards and monitoring

Rationale: Google discontinued public Android dessert names but continued using them internally for "repositories, technical documentation, and team coordination" because the engineering benefits exist independently of customer-facing benefits.

Exception: External Use Where Beneficial (AWS Approach)

Consider external code names when: - Building developer community around a product - Creating competitive differentiation (AWS Lambda example) - Product has strong technical brand identity - Name enhances perception of innovation - Developer-facing product or API

If we build a developer platform or public API where distinctive naming provides competitive advantage, external code names may be appropriate (with business team approval).

Translation Guidelines

Customer/Partner Communication

  • Translate code names to business terms in customer-facing contexts
  • Sales materials use descriptive business language
  • Support documentation references user-visible product names
  • Marketing owns external naming decisions

Technical Documentation

  • Internal docs use code names
  • External developer docs may use code names (if approved for external use)
  • API documentation follows external naming decisions
  • README files in public repositories use business terms unless code name is externally approved

Risk Assessment and Mitigation

Risk: Customer confusion if code names leak into support conversations Mitigation: Clear training for support team on translating between internal and external names

Risk: Partner confusion during technical integrations Mitigation: Technical partnership docs can use code names with clear mapping to business terms

Risk: Inconsistent usage creating more confusion Mitigation: Document clear policy in this ADR, reference in naming registry, include in onboarding materials

DECISION

We will adopt Option 1: Code Names for Major Products as outlined in the Considered Options section.

What We Will Do

Adopt code names for major internal products and services using a themed naming convention selected by engineering teams. This addresses our current naming problems (temporal drift, communication ambiguity, scope creep, architectural coupling) while aligning with industry-standard practices from AWS, Google, Microsoft, and Apple.

Scope and Implementation

  • Scope: Major products only - significant platforms, APIs, and services referenced regularly across teams (e.g., api, new_dashboard, airflow-dags, shared-services, targeted-api). Not every utility script or minor microservice.

  • Naming Convention: Engineers choose names from agreed-upon themes (Space/Astronomy recommended as primary theme, Mythology as secondary). Single-word names that are tech-agnostic, memorable, and globally accessible.

  • Usage: Code names used primarily for internal communication (documentation, meetings, Slack, architecture diagrams). Repository names may remain unchanged - the value comes from using code names in communication, not necessarily from renaming repositories.

  • Implementation: Phased 5-stage rollout starting with theme selection, creating a naming registry, piloting with 3-5 major products, documenting guidelines, then gradual expansion. Platform/Infrastructure team maintains the naming registry.

Rationale

This decision is based on:

  1. Technical Benefits: Prevents costly refactoring, enables architectural flexibility, improves cognitive efficiency, supports system evolution without misleading names
  2. Strategic Benefits: Competitive security, organizational flexibility, risk mitigation, aligns with industry best practices
  3. Cultural Benefits: Increased team ownership, improved morale, clearer communication across engineering and business teams
  4. Real-World Validation: Extensive research showing AWS, Google, Microsoft, and Apple independently converged on this practice for measurable benefits
  5. Immediate Pain Relief: Directly addresses our current problems with new_dashboard, "Offerwall" ambiguity, api generic naming, airflow-dags scope creep, and shared-services vs common confusion

What We Will Not Do

  • No forced repository renames: Existing repos can keep technical names; code names are for communication and documentation
  • No external use by default: Code names remain internal unless explicitly approved for external use (following Google's approach)
  • No renaming of stable, well-understood systems: Only adopt code names for new projects or existing projects experiencing naming problems

CONSEQUENCES

Positive Consequences

Immediate Benefits

  • Resolves current naming ambiguities (Offerwall, api, shared-services vs common)
  • Prevents misleading names from temporal drift (new_dashboard problem)
  • Eliminates scope creep naming issues (airflow-dags containing dbt + Liquibase)
  • Reduces architectural coupling in naming (targeted-api problem)

Developer Productivity

  • Faster communication in meetings and discussions
  • Reduced time spent on clarification
  • Clearer mental models of system relationships
  • More efficient onboarding for new engineers

Technical Debt Reduction

  • Prevents future repository renames
  • Enables refactoring without breaking references
  • Supports architectural evolution without naming constraints
  • Reduces coupling between identity and implementation

Security Improvements

  • Enhanced confidentiality for sensitive projects
  • Leak detection capability for external discussions
  • Safer semi-public communication about internal projects

Team Culture

  • Increased ownership and emotional investment
  • Improved morale through project identity
  • Team bonding around naming and mythology
  • Stronger engineering culture

Strategic Alignment

  • Aligns with industry best practices (AWS, Google, Microsoft, Apple)
  • Demonstrates engineering maturity
  • Positions organization for growth and scaling
  • Creates shared vocabulary across engineering and business

Negative Consequences

Initial Costs

  • Training investment for team members
  • Documentation updates required
  • Time spent selecting themes and initial names
  • Communication overhead during transition

Ongoing Overhead

  • Naming registry maintenance
  • Onboarding materials include code name mappings
  • Potential confusion during transition period
  • Need for clear guidelines and enforcement

External Complexity

  • Translation required for customer/partner communication
  • Sales and support need training on mappings
  • Documentation must maintain both internal and external naming
  • Risk of confusion if guidelines not followed

Risks and Mitigations

Risk Impact Probability Mitigation
Inconsistent adoption across teams Medium Medium Clear policy in ADR, naming registry, include in team onboarding
External customer confusion Medium Low Default to internal-only, clear guidelines for external use
Poor name choices create confusion High Low Follow best practices (single words, themed, engineers choose), learn from AWS anti-examples (Fargate)
Naming registry becomes outdated Low Medium Assign ownership to platform team, include in project kickoff checklist
Resistance from engineering leadership High Medium This ADR with industry research and technical arguments
Teams ignore policy and use descriptive names Medium Medium Include in PR review guidelines, architecture review process

IMPLEMENTATION RECOMMENDATIONS

Phased Approach

Phase 1: Theme Selection (Week 1-2)

  • Engineering teams discuss and vote on preferred theme(s)
  • Follow Rands' rule: Engineers choose, not management
  • Consider multiple themes for different product categories
  • Ensure abundant naming source (won't exhaust with microservices growth)

Phase 2: Create Naming Registry (Week 2)

  • Create simple spreadsheet or documentation page
  • Include columns: Code Name, Technical Repo Name(s), Description, Team Owner, External Name (if different), Status
  • Assign ownership to platform/infrastructure team
  • Add to architecture documentation

Phase 3: Pilot with Major Products (Week 3-4)

  • Start with 3-5 major products experiencing current naming problems
  • Strong candidates: new_dashboard, api, airflow-dags, shared-services, targeted-api
  • Document learnings and refine approach
  • Gather feedback from teams

Phase 4: Document Guidelines (Week 4-5)

  • Formalize internal vs external usage guidelines
  • Create onboarding materials explaining code names
  • Add to team wiki and documentation
  • Include in PR review and architecture review processes

Phase 5: Gradual Rollout (Month 2-3)

  • Extend to remaining major products
  • New projects adopt code names from inception
  • Existing products adopt opportunistically (during major refactoring or architecture changes)
  • No forced renames of stable, well-understood systems

Handling Legacy Repositories

Philosophy: Code names are primarily for communication, documentation, and organizational clarity - not necessarily for repository renaming.

For existing repos like api, new_dashboard, airflow-dags:

  • Assign code name in the naming registry
  • Use code name in all documentation, meetings, Slack discussions, and architecture diagrams
  • Repository name stays unchanged (e.g., api repo keeps its name)
  • Update README to prominently display code name
  • Example: "# Apollo (api repository) - Offerwall API and Services"

Option 2: Repository Rename (Only for high-value cases)

  • Reserve for repositories causing significant confusion (new_dashboard, shared-services)
  • Rename during a planned major refactor or version upgrade to minimize disruption
  • Update CI/CD pipelines, deployment configs, and documentation
  • Communicate widely before and after rename
  • Consider GitHub redirects to minimize broken links

Recommendation Start with Option 1 for all legacy repos. The value comes from using code names in communication and documentation, not from renaming Git repositories. Repository renames should be rare and only when the pain of the current name significantly outweighs the cost of migration.

Naming Registry Structure

Minimum viable naming registry:

Code Name Technical Repo(s) Description Team Owner External Name Status
Example: Aurora new_dashboard Customer dashboard and analytics platform Team Rocket Dashboard Pro Active
Example: Hermes api, offerwall-ui Offerwall API and user interface Team Atlas Offerwall Active

Location docs/naming-registry.md in this repository

Ownership Platform/Infrastructure team maintains, teams submit PRs for additions

Best Practices (Industry Research-Based)

DO:

  • Let engineers choose names (not marketing/management)
  • Use single-word names for communication efficiency
  • Choose themes unrelated to business domain (prevents architectural bias)
  • Ensure global uniqueness across platforms
  • Consider thematic relevance when helpful (but don't force it)
  • Use abundant naming sources (astronomy has thousands of stars, mythology has hundreds of figures)
  • Document rationale in ADR for organizational memory

DON'T:

  • Avoid value-laden terms ("new," "next," "modern," "legacy")
  • Avoid systematic/mechanical naming (Q1-A-4, sequential numbers, RGB colors)
  • Don't use multi-word names (reduces communication efficiency)
  • Avoid completely opaque terms that require explanation (AWS Fargate problem)
  • Don't let marketing or management choose names (Rands' rule)

Code Name Theme Suggestions

Based on research best practices (single words, abundant source, accessible terminology, globally understandable):

1. Space/Astronomy Theme

Abundant source (thousands of options), broadly understood, sense of exploration and innovation

Examples: Nebula, Pulsar, Quasar, Andromeda, Cassini, Voyager, Kepler, Orion, Phoenix, Titan, Vega, Sirius, Polaris, Nova, Cosmos

Pros: Nearly unlimited options, prestigious associations, easy pronunciation globally Cons: Some terms require explanation (pulsar, quasar)

2. Mythology Theme

Rich source (hundreds of figures), strong character associations, memorable

Examples: Atlas, Apollo, Hermes, Athena, Thor, Odin, Artemis, Mercury, Juno, Freya, Loki, Diana, Mars, Neptune

Pros: Strong personalities and stories aid memory, globally recognized Cons: Cultural bias toward Western mythology (mitigate by including global mythologies)

3. Nature Theme

Universally understandable, evokes strength and permanence

Examples: Everest, Sequoia, Aurora, Cascade, Denali, Rainier, Aspen, Summit, Glacier, Canyon, Mesa, Tundra, Savanna, Delta

Pros: Accessible across cultures, strong imagery Cons: Smaller pool than astronomy/mythology

4. Gaming/Adventure Theme

Relevant to gaming industry context, energizing and aspirational

Examples: Quest, Odyssey, Expedition, Achievement, Realm, Saga, Triumph, Victory, Journey, Legend, Epic, Valor, Glory, Champion

Pros: Connects to company industry, motivational Cons: May feel less professional to some, smaller pool

5. Sci-Fi Literature Theme

Appeals to engineering culture, prestigious technical associations

Examples: Foundation, Dune, Neuromancer, Ringworld, Hyperion, Solaris, Ender, Gibson, Asimov, Bradbury, Clarke, Sagan

Pros: Strong engineering culture appeal, rich associations Cons: Requires familiarity with genre, potential IP considerations

Recommendation

Primary Theme: Space/Astronomy - largest pool, globally accessible, prestigious associations, easy pronunciation

Secondary Theme: Mythology - for products needing strong character/personality associations

This provides flexibility while maintaining coherence and ensuring we won't exhaust naming options as we scale.

NOTES

References

Industry Research and Case Studies

  • Artsy Engineering Blog: "Why Projects Need Codenames" - Technical rationale from engineering team
  • IT Pro Today: "Does AWS' Cloud Service Naming Strategy Deliver a Competitive Edge?" - Research analysis of AWS naming impact
  • Rands in Repose (Michael Lopp): "The Codename Rules" - Engineering leadership best practices
  • Stack Overflow Engineering Blog: Code name discussions and technical benefits
  • Google Android Developers Blog: Android version naming decisions and rationale
  • Various company technical blogs documenting naming strategies

Key Quotes

  • Artsy: "Projects don't always match their original scope"
  • AWS research: "Developers feel like they're part of a unique constituency of forward-thinking technology practitioners"
  • Rands: "Engineers building the product should select the codename, not marketing"
  • Google: Continued using dessert names internally for "repositories, technical documentation, and team coordination"
  • ADR-0001: Record Architecture Decisions (establishes approval process)
  • ADR-0004: Representing Architecture Visually (mentions naming in diagrams)

Original Author

Ron White (ronco)

Approval Date

[To be completed upon approval]

Approved By

[To be completed upon approval - requires 2 approvals per ADR-0001]

Revision History

  • 2025-11-17: Initial draft (Ron White)