Linee guida per la formattazione del testo

L'uso coerente e appropriato degli stili grassetto e corsivo e dello stile codice per gli elementi di testo migliora la leggibilità e la chiarezza del testo.

Grassetto

Usare il grassetto per gli elementi dell'interfaccia utente, ad esempio le voci di menu, i nomi delle finestre di dialogo e i nomi dei campi di input.

Esempio

• InEsplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto e quindi scegliere Aggiungi > nuovo elemento.
• Non questo: in Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto e quindi scegliere Aggiungi > nuovo elemento.
• Non questo: in Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto e quindi scegliere Aggiungi > nuovo elemento.

Corsivo

Usare il corsivo per:

• Introduzione di nuovi termini con una definizione o una spiegazione.
• Nomi di file, nomi di cartelle, percorsi.
• Input utente.

Esempio

• Usare: Nel servizio app, un'app viene eseguita in un piano di servizio app. Un piano di servizio app definisce un set di risorse di calcolo per l'esecuzione di un'app Web.
• Non questo: in servizio app, un'app viene eseguita in un "piano di servizio app". Un piano servizio app definisce un set di risorse di calcolo per l'esecuzione di un'app Web.
• Usare: Sostituire il codice in HttpTriggerCSharp.cs con il codice seguente.
• Non usare: Sostituire il codice in HttpTriggerCSharp.cs con il codice seguente.
• Usare: Immettere ContosoUniversity nel campo Nome e quindi selezionare Aggiungi.
• Non usare: Immettere "ContosoUniversity" nel campo Nome e quindi selezionare Aggiungi.

Stile codice

Usare lo stile di codice per:

• Elementi di codice come i nomi dei metodi, i nomi delle proprietà e le parole chiave del linguaggio.
• Comandi SQL
• Nomi dei pacchetti NuGet
• Comandi della riga di comando*
• Nomi di tabelle e colonne di database
• Nomi di risorse che non devono essere localizzati, come i nomi delle macchine virtuali
• URL da rendere non selezionabili

Perché? Nelle guide di stile precedenti era indicato di usare il grassetto per molti di questi elementi di testo. La maggior parte degli articoli viene tuttavia localizzata e lo stile di codice indica al traduttore di lasciare invariata la specifica parte del testo.

Lo stile del codice può essere inline (racchiuso tra ') o blocchi di codice delimitati (racchiusi da ''') che si estendono su più righe. È consigliabile inserire gli snippet di codice e i percorsi lunghi in blocchi di codice delimitati.

* Nei comandi della riga di comando usare le barre nei percorsi di file se sono supportati in tutte le piattaforme. Usare le barre rovesciata per illustrare i comandi eseguiti in Windows, quando sono supportate solo le barre rovesciata. Ad esempio, le barre funzionano nell'interfaccia della riga di comando di .NET in tutte le piattaforme, quindi è consigliabile usare dotnet build foldername/filename.csproj anziché dotnet build foldername\filename.csproj.

Esempi d'uso di stili inline

• Usare: Per impostazione predefinita, Entity Framework interpreta una proprietà denominata Id o ClassnameID come la chiave primaria.
• Non usare: Per impostazione predefinita, Entity Framework interpreta una proprietà denominata Id o ClassnameID come la chiave primaria.
• Usare: Il pacchetto Microsoft.EntityFrameworkCore garantisce il supporto runtime per EF Core.
• Non usare: Il pacchetto Microsoft.EntityFrameworkCore garantisce il supporto runtime per EF Core.

Esempi di blocchi di codice delimitati

• Usare: Il database non riceve nessun comando dalle istruzioni che modificano solo un elemento IQueryable, ad esempio il codice seguente:

      ```csharp
      var students = context.Students.Where(s => s.LastName == "Davolio")
      ```
  

• Non questo: nessun comando viene inviato al database da istruzioni che modificano semplicemente un oggetto IQueryable, ad esempio var students = context. Students.Where(s => s.LastName == "Davolio").

• Usare: Ad esempio, per eseguire lo script Get-ServiceLog.ps1 nella directory C:\Scripts digitare:

      ```powershell
      C:\Scripts\Get-ServiceLog.ps1
      ```
  

• Non usare: Ad esempio, per eseguire lo script Get-ServiceLog.ps1 nella directory C:\Scripts digitare: "C:\Scripts\Get-ServiceLog.ps1."

• Tutti i blocchi di codice delimitati devono avere un tag di linguaggio approvato. Per un elenco dei tag di linguaggio supportati, vedere Come includere codice in Docs.

Segnaposto

Se si desidera che l'utente sostituisca parte di una stringa di input con i propri valori, usare il testo segnaposto contrassegnato da parentesi angolari (minore di < e maggiore di > caratteri).

Opzione 1: Usare lo stile del codice per racchiudere la parola segnaposto o la frase che include. Ad esempio, è possibile usare single backticks ' per la formattazione inline-code per una singola frase o triplo tick ''' per la formattazione delimitata dal codice.

`az group delete -n <ResourceGroupName>`

Rendering eseguito come:

az group delete -n <ResourceGroupName>

oppure

Opzione 2: Usare un carattere \ barra rovesciata per eseguire l'escape dei caratteri delle parentesi angolari in Markdown, ad esempio \< e \>. Anche se è necessaria solo la prima escape sulla parentesi angolare sinistra, l'escape della parentesi \< chiusa \> funziona anche per coerenza. Il codice HTML sottoposto a rendering non mostra il carattere di escape al lettore:

az group delete -n \<ResourceGroupName\>

Rendering eseguito come:

az group delete -n <ResourceGroupName>

Informare il lettore del segnaposto: nel testo precedente tali esempi segnaposto spiegare al lettore che il testo tra parentesi quadre deve essere rimosso e sostituito con valori reali. È consigliabile usare il corsivo per l'input dell'utente. È possibile formattare il corsivo all'interno di codice inline tra parentesi angolari:

Nell'esempio seguente sostituire il testo <ResourceGroupName> segnaposto con il nome del proprio gruppo di risorse.

Attenzione

Il sito di Microsoft Learn non esegue il rendering <del testo segnaposto> che usa parentesi angolari nei casi in cui le parentesi quadre non sono precedute correttamente da un carattere di escape o il testo non è formattato nel codice. Il processo di compilazione di Microsoft Learn interpreta la <frase segnaposto> come tag HTML che potrebbe essere pericolosa per il browser del lettore e la contrassegna come tag html non consentito. Verrà visualizzato un suggerimento nel report di compilazione e il rendering della parola segnaposto non viene eseguito nell'output della pagina di Microsoft Learn in questo caso.

Per evitare la perdita di contenuto nei segnaposto, usare la formattazione o i code caratteri di escape (\<\>) come descritto in precedenza.

È consigliabile usare parentesi graffe { } come segnaposto sintattica. I lettori possono confondere i segnaposto parentesi graffe con la stessa notazione usata in:

• Testo sostituibile
• Stringhe di formato
• Interpolazione di stringhe
• Modelli di testo
• Costrutti di programmazione simili

Maiuscole e minuscole: è possibile separare i nomi segnaposto con trattini ("kebab case") o con caratteri di sottolineatura oppure è possibile farlo usando la combinazione di maiuscole e minuscole Pascal. Il caso kebab potrebbe generare errori di sintassi e i caratteri di sottolineatura potrebbero entrare in conflitto con la sottolineatura. Tutti i maiuscole possono entrare in conflitto con costanti denominate in molte lingue, anche se può anche attirare l'attenzione sul nome segnaposto.

<Resource-Group-Name> o <ResourceGroupName>

Intestazioni e testo dei collegamenti

Non applicare uno stile inline, ad esempio corsivo o grassetto, a intestazioni o testo di collegamento ipertestuale.

Motivo

Le persone identificano gli elementi di testo come collegamenti selezionabili in base alla formattazione standard del testo del collegamento ipertestuale. Lo stile di un collegamento come corsivo, ad esempio, può nascondere il fatto che il testo sia un collegamento. Le intestazioni hanno stili propri che, se combinati con altri stili, possono restituire formattazioni non adeguate.

Esempi di intestazioni e testo di collegamento

• Questo: il file function.json viene generato dal pacchetto NuGet Microsoft.NET.Sdk.Functions.

• Non questo: il file function.json viene generato dal pacchetto NuGet Microsoft.NET.Sdk.Functions.

• Usare:

  ### The Microsoft.NET.Sdk.Functions package
  

• Non usare:

  ### The *Microsoft.NET.Sdk.Functions* package
  

Tasti e scelte rapide da tastiera

Quando si fa riferimento a tasti o combinazioni di tasti, attenersi alle convenzioni seguenti:

• Usare l'iniziale maiuscola per i nomi dei tasti.
• Racchiudere i nomi delle chiavi con <kbd> i tag HTML e </kbd> .
• Usare "+" per unire le chiavi selezionate dall'utente contemporaneamente.

Esempi di tasti e tasti di scelta rapida

• Questo: selezionare ALT+CTRL+S.
• Non usare: Premere ALT+CTRL+S.
• Non usare: Premere ALT+CTRL+S.

Eccezioni

Le linee guida per gli stili non sono regole rigide. Nei contesti in cui queste regole peggiorano la leggibilità, è possibile effettuare scelte differenti. Ad esempio una tabella HTML composta principalmente da elementi di codice può apparire confusa se formattata interamente con lo stile codice. In questo contesto è possibile scegliere di usare lo stile grassetto.

Se si sceglie uno stile di testo alternativo quando è normalmente richiesto lo stile di codice, assicurarsi che il testo debba essere tradotto nelle versioni localizzate dell'articolo. Lo stile di codice è l'unico stile che impedisce automaticamente la traduzione del testo. Per gli scenari in cui si vuole impedire la localizzazione senza usare lo stile di codice, vedere Stringhe non localizzate.