Dokumentowanie kodu przez dodawanie komentarzy i metadanych

4 min

Dobry kod Bicep jest dokumentowaniem własnym. Oznacza to, że używa jasnego nazewnictwa i dobrej struktury, dzięki czemu gdy współpracownicy czytają kod, mogą szybko zrozumieć, co się dzieje. Jeśli trzeba wprowadzić zmiany, mogą mieć pewność, że modyfikują odpowiednie miejsca.

W niektórych sytuacjach może być jednak konieczne wyjaśnienie określonego kodu przez dodanie dodatkowej dokumentacji do plików Bicep. Ponadto po wdrożeniu szablonu i utworzeniu zasobów na platformie Azure ważne jest, aby każda osoba, która patrzy na środowisko platformy Azure, rozumie, co to jest każdy zasób i co jest dla niego.

W tej lekcji dowiesz się, jak dodawać komentarze do plików Bicep i jak używać tagów zasobów do dodawania metadanych do zasobów platformy Azure. Ta dodatkowa dokumentacja zapewnia współpracownikom wgląd w to, co robi twój kod, logikę użytą do pisania kodu i przeznaczenie zasobów platformy Azure.

Dodawanie komentarzy do kodu

Bicep umożliwia dodawanie komentarzy do kodu. Komentarze to tekst czytelny dla człowieka, który dokumentuje kod, ale jest ignorowany podczas wdrażania pliku na platformie Azure.

Bicep obsługuje dwa typy komentarzy:

Komentarze jednowierszowe zaczynają się od podwójnej sekwencji znaków ukośnika (//) i przejdź do końca wiersza, jak pokazano poniżej:

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

Komentarze wielowierszowe używają /* sekwencji znaków i */ do otaczania komentarza i mogą obejmować wiele wierszy, jak pokazano poniżej:
```
/*
  This Bicep file was developed by the web team.
  It deploys the resources we need for our toy company's website.
*/
```

Napiwek

Unikaj używania komentarzy do oczywistych i przejrzystych części kodu. Posiadanie zbyt wielu komentarzy zmniejsza czytelność kodu. Ponadto można łatwo zapomnieć o aktualizowaniu komentarzy, gdy kod ulegnie zmianie w przyszłości. Skoncentruj się na dokumentowaniu unikatowej logiki i złożonych wyrażeń.

Możesz również użyć komentarzy Bicep, aby dodać ustrukturyzowany blok wielowierszowy na początku każdego pliku. Pomyśl o tym jako o manifeście. Twój zespół może zdecydować, że każdy szablon i moduł powinien mieć manifest opisujący przeznaczenie szablonu i jego zawartość, na przykład w tym przykładzie:

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

Dodawanie komentarzy do plików parametrów

Pliki parametrów umożliwiają utworzenie pliku JSON w celu określenia zestawu wartości parametrów dla wdrożenia. Wartości parametrów muszą być zgodne z parametrami zadeklarowanymi w szablonie Bicep.

Wartości określone w plikach parametrów często korzystają również z udokumentowania. Dobrym rozwiązaniem jest dodanie komentarzy do plików parametrów podczas pracy z wartościami parametrów, które mogą nie być natychmiast jasne dla kogoś odczytujące plik.

Na przykład szablon Bicep witryny internetowej może zawierać parametr adresu URL, aby uzyskać dostęp do interfejsu API zapasów produktów firmy, aby witryna internetowa mogła wyświetlić, czy zabawki znajdują się w magazynie. Adresy URL umożliwiające dostęp do interfejsu API giełdowego dla każdego środowiska nie są łatwe do zrozumienia, więc są dobrym kandydatem do komentarza:

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

Napiwek

Podczas pracy z plikami parametrów i innymi plikami JSON, które zawierają komentarze, zwykle należy użyć rozszerzenia pliku jsonc zamiast .json. Pomaga to programowi Visual Studio Code i innym narzędziom zrozumieć, że komentarze są dozwolone.

Dodawanie opisów do parametrów, zmiennych i danych wyjściowych

Podczas tworzenia parametru, zmiennej lub danych wyjściowych można zastosować @description() dekorator, aby ułatwić wyjaśnienie jego przeznaczenia:

@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

Opisy są bardziej zaawansowane niż komentarze, ponieważ gdy ktoś używa rozszerzenia programu Visual Studio Code dla Bicep, opisy są wyświetlane za każdym razem, gdy ktoś umieści wskaźnik myszy na nazwie symbolicznej. Ponadto, gdy ktoś używa pliku Bicep jako modułu, zobaczy opisy stosowane do parametrów.

Dodawanie opisów do zasobów

Warto również dodać opisy do zdefiniowanych zasobów. Można również zastosować @description() dekorator do zasobów.

Ponadto niektóre zasoby obsługują dodawanie opisów lub innych informacji czytelnych dla człowieka do samego zasobu. Na przykład wiele zasobów usługi Azure Policy i przypisań ról kontroli dostępu na podstawie ról (RBAC) platformy Azure zawiera właściwość opisu, taką jak poniżej:

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

Warto użyć tej właściwości, aby wyjaśnić, dlaczego utworzono każde przypisanie roli. Opis jest wdrażany na platformie Azure przy użyciu zasobu, więc każdy, kto przeprowadza inspekcję konfiguracji RBAC środowiska platformy Azure, natychmiast zrozumie przeznaczenie przypisania roli.

Stosowanie tagów zasobów

Komentarze w pliku Bicep nie są wyświetlane w żadnym miejscu we wdrożonych zasobach. Są one dostępne tylko w celu ułatwienia dokumentowania plików Bicep. Istnieje jednak wiele sytuacji, w których należy śledzić informacje o wdrożonych zasobach platformy Azure, w tym:

Przydzielanie kosztów platformy Azure do określonych centrów kosztów.
Zrozumienie, w jaki sposób dane zawarte w bazach danych i kontach magazynu powinny być klasyfikowane i chronione.
Rejestrowanie nazwy zespołu lub osoby odpowiedzialnej za zarządzanie zasobem.
Śledzenie nazwy środowiska, do którego odnosi się zasób, takie jak produkcja lub programowanie.

Tagi zasobów umożliwiają przechowywanie ważnych metadanych dotyczących zasobów. Tagi zasobów definiuje się w kodzie Bicep, a platforma Azure przechowuje informacje z zasobem podczas wdrażania:

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

Tagi zasobu można wykonywać za pomocą narzędzi, takich jak program Azure PowerShell i interfejs wiersza polecenia platformy Azure, a tagi można wyświetlić w witrynie Azure Portal:

Zrzut ekranu witryny Azure Portal dla konta magazynu przedstawiający lokalizację tagów.

Często używa się tego samego zestawu tagów dla wszystkich zasobów, dlatego często dobrym pomysłem jest zdefiniowanie tagów jako parametrów lub zmiennych, a następnie ponowne użycie ich w każdym zasobie: