Condividi tramite

Linee guida per la formattazione del testo

  • Articolo

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.

Esempi

  • 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.
  • 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.

Esempi

  • 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 di servizio app definisce un set di risorse di calcolo per l'esecuzione di un'app Web.
  • Questo: sostituire il codice in HttpTriggerCSharp.cs con il codice seguente.
  • Non questo: sostituire il codice in HttpTriggerCSharp.cs con il codice seguente.
  • Questo: immettere ContosoUniversity come Nome e quindi selezionare Aggiungi.
  • Non questo: immettere "ContosoUniversity" per Nome e quindi selezionare Aggiungi.

Stile del 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 dei file se sono supportate 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 dalle 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 i singoli backticks ' per la formattazione inline del codice per una singola frase o per la formattazione delimitata dal codice.For example, you can use single backticks ' for inline-codecoded formatting for a single phrase, or triple-ticks ''' for code-fenced formatting.

`az group delete -n <ResourceGroupName>`

Rendering eseguito come:

az group delete -n <ResourceGroupName>

or

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 sequenza di 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 di 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 racchiuso tra parentesi angolari:

Nell'esempio seguente sostituire il testo <ResourceGroupName> segnaposto con il proprio nome del 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 escape o il testo non è formattato in codice. Il processo di compilazione di Microsoft Learn interpreta la <frase segnaposto> come tag HTML che potrebbe essere pericoloso per il browser del lettore e lo 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.

Non è consigliabile usare parentesi graffe { } come segnaposto sintattico. I lettori possono confondere segnaposto parentesi graffe con la stessa notazione usata in:

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

Maiuscole e minuscole: è possibile separare i nomi segnaposto con trattini ("maiuscolo kebab") 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 essere in conflitto con la sottolineatura. Tutti i maiuscole possono entrare in conflitto con costanti denominate in molte lingue, anche se può attirare l'attenzione sul nome segnaposto.

<Resource-Group-Name> oppure <ResourceGroupName>

Intestazioni e testo dei collegamenti

Non applicare uno stile inline, ad esempio corsivo o grassetto alle intestazioni o al testo del collegamento ipertestuale.

Perché?

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

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

  • In questo modo, selezionare ALT CTRL++S.
  • Non questo: premere ALT+CTRL+S.
  • Non è questo: 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.