Документирование кода путем добавления комментариев и метаданных

4 мин

Хороший код Bicep самодокументируется. Это означает, что он использует четкое именование и хорошую структуру, чтобы при чтении кода коллеги могли быстро понять, что происходит. А если нужно внести изменения, они могут быть уверены в том, что изменяют нужные места.

Тем не менее бывают ситуации, когда определенный код нужно пояснить, добавив к файлам Bicep дополнительную документацию. Кроме того, важно, чтобы после развертывания шаблона и создания ресурсов в Azure любой, кто будет просматривать вашу среду Azure, понимал суть и назначение каждого ресурса.

В этом разделе вы узнаете, как добавлять комментарии в файлы Bicep и использовать теги ресурсов для добавления метаданных в ресурсы Azure. Эта дополнительная документация предоставляет коллегам аналитические сведения о том, что делает ваш код, логика, используемая для написания кода, и назначение ресурсов Azure.

Добавление комментариев в код

Bicep позволяет добавлять комментарии в код. Комментарии — это удобочитаемый текст, который документирует код, но не принимается во внимание, когда файл развертывают в Azure.

Bicep поддерживает комментарии двух типов.

Однострочные комментарии начинаются с двойной косой черты (//) и продолжаются до конца строки, как показано ниже.

// We need to define a firewall rule to allow Azure services to access the database.

resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = {
  parent: sqlServer
  name: 'AllowAllAzureIPs'
  properties: {
    startIpAddress: '0.0.0.0' // This combination represents 'all Azure IP addresses'.
    endIpAddress: '0.0.0.0'
  }
}

Многострочные комментарии открываются и закрываются последовательностями символов /* и */ и могут занимать сразу несколько строк, как показано ниже.
```
/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/
```

Совет

Старайтесь не использовать комментарии для очевидных и понятных фрагментов кода. Избыток комментариев затрудняет чтение кода. Кроме того, можно забыть обновить комментарии, если в будущем ваш код будет изменен. Документируйте уникальную логику и сложные выражения.

Также с помощью комментариев Bicep можно добавлять в начало каждого файла структурированный многострочный блок. Его можно рассматривать как манифест. Ваша команда может договориться в каждый шаблон и модуль включать манифест, описывающий назначение и содержимое шаблона, как в этом примере.

/*
  SYNOPSIS: Module for provisioning Azure SQL server and database.
  DESCRIPTION: This module provisions an Azure SQL server and a database, and configures the server to accept connections from within Azure.
  VERSION: 1.0.0
  OWNER TEAM: Website
*/

Добавление комментариев к файлам параметров

Файлы параметров позволяют создать JSON-файл, чтобы указать набор значений параметров для развертывания. Значения параметров должны соответствовать параметрам, объявленным в шаблоне Bicep.

Значения, указанные в файлах параметров, тоже часто полезно документировать. Добавляйте комментарии в файлы параметров при работе со значениями параметров, которые могут быть неочевидны для пользователя, читающего файл.

Например, шаблон Bicep для веб-сайта может включать параметр URL-адреса для доступа к API складских запасов вашей компании, необходимый для того, чтобы веб-сайт показывал наличие ваших игрушек на складе. URL-адреса для доступа к API складских запасов в каждой среде не так просты для понимания, поэтому их хорошо бы снабдить комментарием.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
      "productStockCheckApiUrl": {
        "value": "https://x73.mytoycompany.com/e4/j7" // This is the URL to the product stock API in the development environment.
      }
    }
  }

Совет

При работе с файлами параметров и другими JSON-файлами, которые содержат комментарии, обычно необходимо использовать расширение файла JSONC, а не JSON. Это показывает Visual Studio Code и другим средствам, что комментарии разрешены.

Добавление описаний к параметрам, переменным и выходным данным

При создании параметра, переменной или выходных данных можно применить декоратор @description(), чтобы объяснить их назначение:

@description('The Azure region into which the resources should be deployed.')
param location string = resourceGroup().location

@description('Indicates whether the web application firewall policy should be enabled.')
var enableWafPolicy = (environmentType == 'prod')

@description('The default host name of the App Service app.')
output hostName string = app.properties.defaultHostName

Описания эффективнее комментариев, поскольку при использовании расширения Visual Studio Code для Bicep, описания отображаются всякий раз, когда пользователь наводит указатель мыши на символическое имя. Кроме того, при использовании файла Bicep в качестве модуля пользователь видит описания, примененные к параметрам.

Добавление описаний к ресурсам

Полезно также добавлять описания к ресурсам, которые вы определяете. Вы также можете применить декоратор @description() к ресурсам.

Кроме того, некоторые ресурсы поддерживают добавление описаний или других удобочитаемый сведений в сам ресурс. Например, многие ресурсы политики Azure и назначения ролей управления доступом на основе ролей (RBAC) в Azure включают свойство описания, например:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(roleDefinitionId, resourceGroup().id)
  properties: {
    principalType: 'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: principalId
    description: 'Contributor access on the storage account is required to enable the application to create blob containers and upload blobs.'
  }
}

Это свойство позволяет объяснить цель назначения каждой роли. Описание развертывается в Azure вместе с ресурсом, поэтому любой пользователь, который проверяет конфигурацию RBAC среды Azure, сразу же понимает назначение ролей.

Применение тегов ресурсов

Комментарии в файле Bicep не отображаются в развернутых ресурсах. Они нужны только для того, чтобы документировать файлы Bicep. При этом часто возникают ситуации, когда сведения о развернутых ресурсах Azure нужно отслеживать, например:

распределение затрат Azure по определенным центрам затрат;
понимание принципов классификации и защиты данных в базах данных и учетных записях хранения;
запись названия команды или имени человека, ответственных за управление ресурсами;
отслеживание имени среды, к которой относится ресурс, например рабочей среды или среды разработки.

Теги ресурсов позволяют хранить важные метаданные о ресурсах. Вы определяете теги ресурсов в коде Bicep, а при развертывании Azure сохраняет информацию вместе с ресурсом.

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  tags: {
    CostCenter: 'Marketing'
    DataClassification: 'Public'
    Owner: 'WebsiteTeam'
    Environment: 'Production'
  }
  sku: {
    name: storageAccountSkuName
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Теги ресурса можно запрашивать с помощью таких инструментов, как Azure PowerShell и Azure CLI, а также просматривать на портале Azure.

Снимок экрана с учетной записью хранения на портале Azure, показывающий расположение тегов

Обычно для всех ресурсов используется один и тот же набор тегов, поэтому часто рекомендуется определять теги как параметры или переменные, а затем использовать их снова в каждом ресурсе.