Documentar o código adicionando comentários e metadados

  • 4 minutos

Um bom código Bicep é autodocumentado. Isso significa que ele usa uma nomenclatura clara e uma estrutura adequada, de modo que quando os colegas lerem seu código, eles possam entender rapidamente o que está acontecendo. Caso precisem fazer alterações, eles podem ter a certeza de que estão modificando os locais certos.

No entanto, em algumas situações, talvez seja necessário esclarecer determinado código adicionando uma documentação extra aos arquivos Bicep. Além disso, depois que o modelo for implantado e os recursos forem criados no Azure, será importante que qualquer pessoa que examinar seu ambiente do Azure entenda o que é cada recurso e para que ele serve.

Nesta unidade, você aprenderá a adicionar comentários aos arquivos Bicep e a usar marcas de recurso para adicionar metadados aos recursos do Azure. Esta documentação adicional fornece aos seus colegas insights sobre o que o código faz, a lógica usada para escrevê-lo e a finalidade dos recursos do Azure.

Adicionar comentários ao código

O Bicep permite que você adicione comentários ao código. Os comentários são um texto legível que documenta o código, mas que é ignorado quando o arquivo é implantado no Azure.

O Bicep dá suporte a dois tipos de comentários:

  • Os comentários de linha única começam com uma sequência de caracteres de barra dupla (//) e continuam até o final da linha, conforme mostrado aqui:

    // 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'
  }
}

  • Os comentários de várias linhas usam as sequências de caracteres /* e */ para envolver o comentário e podem abranger várias linhas, conforme mostrado aqui:

    /*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/

Dica

Evite usar comentários para partes óbvias e claras do código. A presença de muitos comentários, na verdade, reduz a legibilidade do código. Além disso, será fácil esquecer de atualizar os comentários quando o código for alterado no futuro. Concentre-se em documentar a lógica exclusiva e as expressões complexas.

Use também os comentários do Bicep para adicionar um bloco de várias linhas estruturado no início de cada arquivo. Considere-o como um manifesto. Sua equipe pode decidir que cada modelo e módulo devem ter um manifesto que descreva a finalidade do modelo e o que ele contém, como neste exemplo:

/*
  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
*/

Adicionar comentários a arquivos de parâmetros

Os arquivos de parâmetros permitem que você crie um arquivo JSON para especificar um conjunto de valores de parâmetros para sua implantação. Os valores de parâmetros precisam corresponder aos parâmetros declarados no modelo Bicep.

Em geral, os valores que você especifica em arquivos de parâmetros se beneficiam da documentação. É uma boa prática adicionar comentários aos arquivos de parâmetros quando você trabalha com valores de parâmetros que podem não ser imediatamente claros para alguém que leia o arquivo.

Por exemplo, o modelo Bicep do seu site pode incluir um parâmetro para a URL usada para acessar a API de estoque do produto da sua empresa, de modo que o site possa exibir se os brinquedos estão em estoque no depósito. As URLs usadas para acessar a API de estoque para cada ambiente não são fáceis de serem entendidas. Portanto, elas são boas candidatas para um comentário:

{
    "$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.
      }
    }
  }

Dica

Quando você trabalha com arquivos de parâmetros e outros arquivos JSON que incluem comentários, normalmente, é preciso usar a extensão de arquivo .jsonc em vez de .json. Isso ajuda a Visual Studio Code e outras ferramentas a entender que os comentários são permitidos.

Adicionar descrições a parâmetros, variáveis e saídas

Ao criar um parâmetro, uma variável ou uma saída, você pode aplicar o decorador @description() para ajudar a explicar sua finalidade:

@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

As descrições são mais eficientes do que os comentários, porque quando alguém usa a extensão Visual Studio Code para Bicep, as descrições são mostradas sempre que alguém passa o mouse sobre um nome simbólico. Além disso, quando alguém usa o arquivo Bicep como um módulo, ele verá as descrições que você aplica aos parâmetros.

Adicionar descrições aos recursos

Também pode ser útil adicionar descrições aos recursos que você definir. Você também pode aplicar o decorador @description() a recursos.

Adicionalmente, alguns recursos dão suporte à adição de descrições ou de outras informações legíveis ao próprio recurso. Por exemplo, muitos recursos do Azure Policy e muitas atribuições de função RBAC (controle de acesso baseado em função) do Azure incluem uma propriedade de descrição, desta forma:

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.'
  }
}

É uma boa ideia usar essa propriedade para explicar por que você criou cada atribuição de função. A descrição é implantada no Azure com o recurso, portanto, qualquer pessoa que audita a configuração de RBAC do ambiente do Azure entenderá imediatamente a finalidade da atribuição de função.

Aplicar marcas de recurso

Os comentários no arquivo Bicep não são exibidos em nenhum lugar nos recursos implantados. Eles só estão presentes nele para ajudar você a documentar os arquivos Bicep. No entanto, há muitas situações em que é preciso acompanhar informações sobre os recursos do Azure implantados, incluindo:

  • Alocar os custos do Azure para centros de custo específicos.
  • Entender como os dados contidos em bancos de dados e contas de armazenamento devem ser classificados e protegidos.
  • Registrar o nome da equipe ou da pessoa responsável pelo gerenciamento do recurso.
  • Acompanhar o nome do ambiente ao qual o recurso se relaciona, como produção ou desenvolvimento.

As marcas de recurso permitem armazenar metadados importantes sobre os recursos. Você define as marcas de recurso no código Bicep, e o Azure armazena as informações com o recurso quando ele é implantado:

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'
  }
}

Consulte as marcas de um recurso usando ferramentas como o Azure PowerShell e a CLI do Azure e veja as marcas no portal do Azure:

Captura de tela do portal do Azure para uma conta de armazenamento, que mostra a localização das marcas.

É comum usar o mesmo conjunto de marcas para todos os recursos. Portanto, em geral, é uma boa ideia definir as marcas como parâmetros ou variáveis e reutilizá-las em cada recurso:

param tags object = {
  CostCenter: 'Marketing'
  DataClassification: 'Public'
  Owner: 'WebsiteTeam'
  Environment: 'Production'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  tags: tags
}

resource appServiceApp 'Microsoft.Web/sites@2023-12-01' = {
  tags: tags
}