Introduction
Choosing a good name for a software project is a critical task, as it will be referenced multiple times in building pipelines, configurations, logs, documentation, deployment packages, software dependencies, emails, discussions, and early morning support calls.
To avoid common issues related to software names it is important to follow a convention that minimise incompatibilities between technologies, platforms and usage case scenarios.
Here is proposed a convention that works well in the aforementioned multiple situations.
Common Character Set
All projects must be named using only the lower case ASCII characters from “a” to “z”, numbers from 0 to 9, and the dash symbol “-” as a word separator.
abcdefghijklmnopqrstuvwxyz
0123456789
-
The dash symbol “-” is the only allowed delimiter for name parts.
Name Prefixes
In order to be able to quickly differentiate across different types of software projects it is a good practice to use standard 3-characters prefixes:
lib-name: Software libraries.srv-name: Software services. Unlike libraries, services are instantiated and executed directly, and are normally an HTTP service or a pipeline component.app-name: Software applications. They are usually used for websites or mobile apps that sit on the internal platform but are not part of it.cfg-name: Software configuration. It only contains configuration data for the named software.doc-name: Software documentation. It only contains documentation for the named software.
Project Name
The name part can be an unique descriptive name or a code-name (e.g. pdf-parser or einstein). Unless an obvious, short and descriptive name is available (e.g. json-parser), an unique code-name is preferred.
The following rules must apply:
- stick to English;
- don’t try to shorten words to fit into a descriptive name;
- use the phonetic alphabet as we want names that are easy to distinguish and pronounce;
- avoid language special-cases, like silent letters;
- use maximum two words or 15 characters;
- if the name has two words, use a dash between them (e.g. xml-parser).
To avoid any confusion and improve traceability, the full name of the software project (e.g. lib-pdf) will be also the name of the CVS repository (i.e. GitHub, Stash, …), the name of the CI/CD building pipeline and the base name for the packaging (i.e. RPM, DEB, Docker, Composer, etc.). In this way it will be immediately clear to anyone what refers to what.