Starting a new Azure Infrastructure as Code (IaC) project can be a challenging task. Establishing clear and concise guidelines for team members is crucial to write consistent, maintainable, and efficient code. This blog post outlines some basic guidelines that can help streamline the process and set a solid foundation for your Azure IaC projects.

Tip: Feel free to copy/paste the following guidelines into a CONTRIBUTING file and save it into the root directory of your project.

By following these guidelines, team members can contribute effectively to Azure IaC and Azure DevOps projects, ensuring a consistent and high-quality codebase. Happy 💪 coding!

Contributing Azure IaC w/Bicep

Coding guidelines

To make life easier, a .vscode/settings.json file is configured to enforce some of the syntax and style guidelines automatically. These will apply when Saving a file for example ps1, bicep, json, yaml or md files. For this to work you need to install the recommended extensions in vscode.

  • Use PascalCase for all public identifiers like module names, function names, properties, parameters, global variables and constants.
  • Use camelCase for all variables within functions (or modules) to distinguish private variables from parameters.
  • Use camelCase for all keys within Json files.
  • Use four spaces per indentation level.
  • Avoid using line continuation characters (`) in PowerShell code and examples.
  • Use PowerShell splatting to reduce line length for cmdlets that have several parameters.
  • Use approved verbs for PowerShell Commands.
  • Take notice of the PowerShell development guidelines when you write modules or cmdlets.
  • Take notice of the PowerShell-Docs style guide when you write documentation content.

Naming convention

The information in resource names ideally includes whatever you need to identify specific instances of resources. For example, a public IP address (PIP) for a production SharePoint workload in the West Europe region might be:

sub-gov-guardians-prd-weu-001
\_/ \_/ \_______/ \_/ \_/ \_/
 1   2      3      4   5   6

Diagram 1: Components of an Azure resource name

  1. Resource type
    An abbreviation that represents the type of Azure resource or asset. Examples, sub, rg, sg, id

  2. Prefix
    A random prefix to ensure globally unique names. Examples, e2egov, jh3gb4

  3. Workload / Application / Service
    Name of the application, workload, or service that the resource is a part of. Examples, avengers, guardians, galaxy

  4. Environment
    The environment to support RBAC. Examples, prd, dev, shared

  5. Azure region (optional)
    The Azure region where the resource is deployed. Examples, weu, eus, wus

  6. Instance (optional)
    The instance count for a specific resource, to differentiate it from other resources that have the same naming convention and naming components. Examples, 001

Visual Studio Code

Settings

Create a .vscode/settings.json file, copy and paste the following JSON, and then adjust it according to your requirements.

{
    "[bicep]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 2
    },
    "[json]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4,
        "editor.detectIndentation": false
    },
    "[markdown]": {
        "files.encoding": "utf8"
    },
    "[powershell]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4,
        "files.encoding": "utf8bom",
        "editor.formatOnSave": true
    },
    "[yaml]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 2
    },
    "editor.formatOnPaste": true,
    "editor.formatOnSave": true,
    "editor.insertSpaces": true,
    "files.insertFinalNewline": true,
    "files.trimTrailingWhitespace": false,
    "markdown.extension.orderedList.marker": "one",
    "markdown.extension.tableFormatter.enabled": false,
    "powershell.scriptAnalysis.settingsPath": "PSScriptAnalyzerSettings.psd1",
    "powershell.codeFormatting.autoCorrectAliases": true,
    "powershell.codeFormatting.newLineAfterCloseBrace": false,
    "powershell.codeFormatting.pipelineIndentationStyle": "IncreaseIndentationForFirstPipeline",
    "powershell.codeFormatting.preset": "OTBS",
    "powershell.codeFormatting.trimWhitespaceAroundPipe": true,
    "powershell.codeFormatting.useConstantStrings": true,
    "powershell.codeFormatting.useCorrectCasing": true,
    "powershell.codeFormatting.whitespaceBetweenParameters": true,
    "javascript.preferences.quoteStyle": "single",
    "typescript.preferences.quoteStyle": "single",
    "yaml.format.singleQuote": true
}

Extensions

Create a .vscode/extensions.json file, copy and paste the following JSON, and then adjust it according to your requirements.

{
    "recommendations": [
        "GitHub.copilot",
        "GitHub.copilot-chat",
        "yzhang.markdown-all-in-one",
        "pspester.pester-test",
        "ms-vscode.powershell",
        "bewhite.psrule-vscode",
        "streetsidesoftware.code-spell-checker",
        "redhat.vscode-yaml"
    ]
}

Markdown styling

Use alerts to provide distinctive styling for significant content.

📄 Note
Highlights information that users should take into account, even when skimming.

💡 Tip
Optional information to help a user be more successful.

🛟 Important
Crucial information necessary for users to succeed.

⚠️ Warning
Critical content demanding immediate user attention due to potential risks.

⛔ Caution
Negative potential consequences of an action.

Terminology

  • lowercase - all lowercase, no word separation.
  • UPPERCASE - all capitals, no word separation.
  • PascalCase - capitalize the first letter of each word.
  • camelCase - capitalize the first letter of each word except the first.
  • kebab-case - all lowercase, with dash (-) word separation.
  • snake_case - all lowercase, with underscore (_) word separation.

Resources

Please take notice of the following documentation: