Naming Conventions

To keep things consistent across various efforts and systems, a convention for the naming of various identifiers is important. This document lays them out clearly, by identifier type.

Repository Naming Conventions

Naming the repositories under a DevOps project has no explicit conventions. Instead, a requirement is that a convention be set by the project team(s). The decided convention should result in names that are consistent and concise.

Solution Naming Conventions

A “solution” here refers not just to Visual Studio solutions (.sln) but to any IDE/language environment where several modules are encapsulated by a single container.

The naming convention for these containers is straightforward: <project-name>.<component-name>. The component-name part refers to which component in the system is represented by this collection of modules.

Optionally, the company name can be prefixed as well, as in <company-name>.<project-name>.<component-name>. If selected, this should be consistent across all solutions in the entire DevOps project (even across repos).

Some examples:

• Atlas.AlertingStudio.AuthAPI
• SelfServiceStudio.SchemaManagement

Often, in more microservice-oriented systems, solutions will have fewer modules within them, which reduces the need for broadly applicable names that identify an entire component of a system.

Module Naming Conventions

When naming modules, use a convention similar to naming solutions: <project-name>.<component-name>.<module-name>. Again, company name can be prefixed but should be consistent across all solutions in the DevOps project if selected.

You have the following 4 types of projects:

• API — Your interface that people use to reach your application. For a Service or Daemon you can rename this to Service. For example: Atlas.WorkQueue.Api or Atlas.WorkQueue.Services.
• Services — This is where rubber meets the road. Some people prefer to just skip the extension, which is fine. So e.g. Atlas.WorkQueue.
• Data — This is where your interface to data persistence lives. If you’re using an http restful endpoint or whatever it’s all the same; data is data, regardless of source.
• Contracts — This is where your interfaces, POCOs, and other shareable pieces live. Should take ZERO dependencies on anything that isn’t provided by the framework.
• Tests — Tests.

Use these to help inform the names of your modules. Examples:

• Atlas.AlertingStudio.AuthAPI.Service
• SelfServiceStudio.SchemaManagement.Contracts
• Atlas.AlertingStudio.AuthAPI.Tests

Anti-Patterns in Module Naming

DO NOT name your module any of the following:

• Helper or variations
  • Frequently, helper classes are used as shortcuts or patches to smooth over problems with application structure.
  • Additionally, calling something a “helper” doesn’t provide any detail as to what the module is helping with and what that “help” is meant to achieve.
• Utilities or variations
  • These are almost always static classes whose names provide no documentation of intent.
  • Very often, they indicate a failure to perform proper dependency injection, as taking a hard dependency on a static class goes against the principle of inversion of control.
• Shared or variations
  • For example, naming a module SharedLib does nothing to imply the purpose of the module.
  • Why is it being shared? What does it provide?
  • Often, modules with names like these are being used to patch over separation of concerns issues by incorrectly or inappropriately sharing code between other modules.

Usage of these names almost always indicates a failure in design, as referenced in the sub-points above.

Code Object and Variable Naming Conventions

These will differ between various programming languages. However, avoid certain patterns such as:

• Hungarian notation
• Other type-prefixed or postfixed names
  • Identifiers should indicate intent/purpose, not language semantics, unless their purpose is specifically related to language semantics (e.g. ConvertRowToTuple<T>()).
• Single-letter names, or heavily abbreviated identifiers
  • Code is meant to be readable by humans

C# conventions can be found here.

Python conventions can be found here.

For languages that do not have explicit conventions, follow general guidelines laid out here and reach out to your team lead(s) for more information and to create a convention.

Anti-Patterns in Object Naming

All of the rules that apply to module naming apply here as well.