The 10 commandments for Azure naming conventions
There are many Azure related naming conventions guides but this one is mine! For every 10 engineers and architects asked you will get 10 different replies on such a topic as naming conventions. With this blog post I would like to kick-off a small series of blog posts sharing my view points about Azure related naming conventions. In this post starting with why a proper naming convention is important and the 10 commandments I generally follow when working on a naming convention.
Why is a proper naming convention important?
A naming convention is a set of rules for choosing the character sequence to be used for identifiers which denote variables, types, functions, and other entities in source code and documentation. source - Wikipedia
By adoption naming conventions on important and widely used area’s we strife to achieve the following benefits:
- To reduce the effort needed to read and understand source code.
- To enable code reviews to focus on issues more important than syntax and naming standards.
- To enable code quality review tools to focus their reporting mainly on significant issues other than syntax and style preferences.
- To provide additional information (i.e., metadata) about the use to which an identifier is put.
- To help formalize expectations and promote consistency within a development team.
- To enable the use of automated refactoring or search and replace tools with minimal potential for error.
- To enhance the aesthetic and professional appearance of work product.
- To provide meaningful data to be used in project handovers.
- To provide better understanding in case of code reuse after a long interval of time.
The 10 commandments
It is important to ensure that automation is able to process objects without creating exceptions for parsing rules and at the same time all developers, engineers and architects should also be able to easily understand the names of all objects. Depending on the objects to which a naming convention applies the focus should either lean more towards automation or towards people (I will elaborate my view on this in the following blog posts of this series). But generally speaking this still should be be achievable by using the following 10 naming commandments.
- Names used should be in correct American English. Why American English? Well because that is the established international language for programming.
- Commonly accepted short forms or abbreviations of long words should be used for brevity. For example, API is preferred over Application Programming Interface.
- Use intuitive, familiar terminology where possible. For example, when describing removing (and destroying) a resource, delete is preferred over erase
- Use the same name or term for the same concept, including for concepts shared across subject domains.
- Avoid name overloading. Use different names for different concepts.
- Avoid overly general names that are ambiguous in a larger ecosystem. They can lead to misunderstanding of objects. Rather, choose specific names that accurately describe the object. For example, when script that automates a number of test actions don’t call it automation call it specific like test-automation
- Carefully consider use of names that may conflict with keywords in common programming languages. Such names may be used but will likely trigger additional scrutiny during review. Use them judiciously and sparingly.
- Ensure that the chosen case type (kebab-case-example, snake_case_example, camelCaseExample, PascalCaseExample, etc) is usable in as many systems, products and tools and stick with it. For example, some web-based systems don’t allow snake_case as it uses underscores and there are others that don’t allow for hyphens making kebab-case undesirable.
- Avoid using organizational structures as departments or business units of companies & organizations in a naming convention. Companies get merged and restructured on a regular basis, so nothing is as fleeting as a department name or a business unit within a company.
- Assume that a name is immutable and cannot be renamed. Azure resource names are like that by design so using this as the reference for any Azure related naming convention is a solid approach as it prevents drift with regards to consistency of the naming convention spanning various products.
Thank you for reading, and don’t forget to check out the next blog post of this series!