Del via

Retningslinjer for tekstformatering

  • Artikkel

Konsekvent og riktig bruk av fet, kursiv og kodestil for tekstelementer forbedrer lesbarheten og bidrar til å unngå misforståelser.

Fet

Bruk fet for brukergrensesnittelementer, for eksempel menyvalg, dialogboksnavn og inndatafeltnavn.

Eksempler

  • Dette: Høyreklikk prosjektnoden i Løsningsutforsker, og velg deretter Legg til > nytt element.
  • Ikke dette: Høyreklikk prosjektnoden i Løsningsutforsker, og velg deretter Legg til > nytt element.
  • Ikke dette: Høyreklikk prosjektnoden i Løsningsutforsker, og velg deretter Legg til > nytt element.

Kursiv

Bruk kursiv til:

  • Presentasjon av nye vilkår og betingelser, sammen med en definisjon eller forklaring.
  • Filnavn, mappenavn, baner.
  • Brukerinndata.

Eksempler

  • Dette: I App Service kjører en app i en apptjenesteplan. En App Service plan definerer et sett med databehandlingsressurser som et webprogram kan kjøre på.
  • Ikke dette: I App Service kjører en app i en «App Service-plan». En App Service-plan definerer et sett med databehandlingsressurser som en nettapp kan kjøre på.
  • Dette: Erstatt koden i HttpTriggerCSharp.cs med følgende kode.
  • Ikke dette: Erstatt koden med HttpTriggerCSharp.cs følgende kode.
  • Dette: Skriv inn ContosoUniversity for navnet, og velg deretter Legg til.
  • Ikke dette: Skriv inn ContosoUniversity for navnet, og velg deretter Legg til.

Kodestil

Bruk kodestil for:

  • Kodeelementer, for eksempel metodenavn, egenskapsnavn og språknøkkelord.
  • SQL kommandoer
  • NuGet-pakkenavn
  • Kommandolinjekommandoer*
  • Databasetabell og kolonnenavn
  • Ressursnavn som ikke skal lokaliseres (for eksempel navn på virtuelle maskiner)
  • URL-adresser som du ikke vil at skal kunne klikkes

Hvorfor? Eldre stilveiledninger angir fet for mange av disse tekstelementene. De fleste artiklene er imidlertid lokalisert, og kodestilen forteller oversetteren at den delen av teksten ikke skal oversettes.

Kodestil kan være innebygd (omgitt av ') eller inngjerdede kodeblokker (omgitt av '') som strekker seg over flere linjer. Legg lengre kodesnutter og-baner i gjerdede kodeblokker.

* Bruk skråstreker i filbaner i kommandolinjekommandoer hvis de støttes på alle plattformer. Bruk omvendte skråstreker til å illustrere kommandoer som kjører på Windows, når bare omvendte skråstreker støttes. Videresend skråstreker fungerer for eksempel på .NET CLI på alle plattformer, så du vil bruke dotnet build foldername/filename.csproj i stedet dotnet build foldername\filename.csprojfor .

Eksempler på bruk av innebygde stiler

  • Dette: Enhetsrammeverket tolker som standard en egenskap som heter Id eller ClassnameID som primærnøkkel.
  • Ikke dette: Enhetsrammeverket tolker som standard en egenskap med navnet ID eller ClassnameID som primærnøkkel.
  • Dette: Pakken Microsoft.EntityFrameworkCore gir kjøretidsstøtte for EF Core.
  • Ikke dette: Microsoft.EntityFrameworkCore-pakken gir kjøretidsstøtte for EF Core.

Eksempler på inngjerdede kodeblokker

  • Dette: Ingen kommandoer sendes til databasen av setninger som bare endrer en IQueryable, for eksempel følgende kode:

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

  • Ikke dette: Ingen kommandoer sendes til databasen etter setninger som bare endrer en IQueryable, for eksempel var studenter = kontekst. Students.Where(s => s.LastName == "Davolio").

  • Dette: Hvis du for eksempel vil kjøre skriptet Get-ServiceLog.ps1 i katalogen C:\Scripts , skriver du inn:

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

  • Ikke dette: Hvis du for eksempel vil kjøre Get-ServiceLog.ps1-skriptet i C:\Skript-katalogen , skriver du inn C:\Scripts\Get-ServiceLog.ps1.

  • Alle inngjerdede kodeblokker må ha en godkjent språkkode. Hvis du vil ha en liste over støttede språkkoder, kan du se hvordan du inkluderer kode i docs.

Plassholdere

Hvis du vil at brukeren skal erstatte en del av en inndatastreng med sine egne verdier, kan du bruke plassholdertekst merket med vinkelparenteser (mindre enn < og større enn > tegn).

Alternativ 1: Bruk kodestil til å omslutte plassholderordet eller det omfattende uttrykket. Du kan for eksempel bruke enkel backticks for innebygd kodeformatering for ett enkelt uttrykk, eller trippel-ticks '' for kodeinngjerdet formatering.

`az group delete -n <ResourceGroupName>`

Gjengitt som:

az group delete -n <ResourceGroupName>

or

Alternativ 2: Bruk et omvendt skråstrek \ til å unnslippe vinkelparentestegnene i Markdown, for eksempel \< og \>. Selv om bare den første flukten på venstre vinkelparentes \< er nødvendig, fungerer det også for konsekvens å unnslippe høyre hakeparentes \> . Den gjengitte HTML-koden viser ikke escape-tegnet til leseren:

az group delete -n \<ResourceGroupName\>

Gjengitt som:

az group delete -n <ResourceGroupName>

Informer leseren om plassholderen: I teksten foran slike plassholdereksempler forklarer du leseren at teksten i hakeparenteser må fjernes og erstattes med reelle verdier. Vi anbefaler bruk av kursiv for brukerinndata. Du kan formatere kursiv innenfor vinkelparentes i linjebundet kode:

I eksemplet nedenfor erstatter du plassholderteksten <ResourceGroupName> med ditt eget ressursgruppenavn.

Forsiktig!

Microsoft Learn-nettstedet gjengir <ikke plassholdertekst> som bruker vinkelparenteser i tilfeller der hakeparentesene ikke er brutt riktig, eller teksten ikke er kodeformatert. Microsoft Learn-byggeprosessen tolker plassholderuttrykket <> som en HTML-kode som kan være farlig for leserens nettleser, og flagger det som en ikke-tillatt HTML-kode. Du ser et forslag i byggrapporten, og plassholderordet gjengis ikke i microsoft Learn-sideutdataene når dette skjer.

Hvis du vil unngå tap av innhold på plassholdere, kan du bruke code formatering eller escape-tegn (\< \>) som beskrevet tidligere.

Vi fraråder å bruke klammeparenteser { } som syntaktiske plassholdere. Lesere kan forvirre klammeparentesplassholdere med samme notasjon som brukes i:

  • Tekst som kan erstattes
  • formatstrenger
  • Strenginterpolasjon
  • Tekstmaler
  • Lignende programmeringskonstruksjoner

Foringsrør og avstand: Du kan skille plassholdernavn med bindestreker ("kebabtilfelle") eller med understrekingstegn, eller du kan gjøre det ved hjelp av Pascal-saken. Kebab-saken kan generere syntaksfeil, og understreking kan komme i konflikt med understreking. Store bokstaver kan komme i konflikt med navngitte konstanter på mange språk, men det kan også rette oppmerksomheten mot plassholdernavnet.

<Resource-Group-Name> eller <ResourceGroupName>

Overskrifter og koblingtekst

Ikke bruk en innebygd stil, for eksempel kursiv eller fet på overskrifter eller hyperkoblingstekst.

Hvorfor?

Personer bruker standard hyperkoblingstekst til å identifisere tekstelementer som klikkbare koblinger. Styling av en kobling som kursiv, for eksempel, kan skjule det faktum at teksten er en kobling. Overskrifter har sine egne stiler og å blande andre stiler i dem ser ikke bra ut.

Eksempler på overskrifter og koblingstekst

  • Dette: Den function.json filen genereres av NuGet-pakken Microsoft.NET.Sdk.Functions.

  • Ikke dette: Filen function.json genereres av NuGet-pakken Microsoft.NET.Sdk.Functions.

  • Denne:

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

  • Ikke denne:

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

Taster og hurtigtaster

Følg disse konvensjonene når du refererer til taster eller tastekombinasjoner:

  • Bruk stor bokstav i nøkkelnavn.
  • Omgi nøkkelnavnene med <kbd> og </kbd> HTML-koder.
  • Bruk «+» til å koble sammen nøkler som brukeren velger samtidig.

Eksempler på taster og hurtigtaster

  • Dette: Velg ALT+CTRL+S.
  • Ikke dette: Trykk ALT+CTRL+S.
  • Ikke dette: Hit ALT+CTRL+S.

Unntak

Stil retning linjer er ikke rigide regler. I sammenhenger der de skade lesbarheten, gjør noe annerledes. For eksempel kan en HTML-tabell med begge kodeelementene se uryddig ut, med kodestiler overalt. Du kan velge fet stil i den konteksten.

Hvis du velger en alternativ tekststil der koden normalt blir bedt om, må du sørge for at det er greit at teksten blir oversatt i lokaliserte versjoner av artikkelen. Kode er den eneste stilen som automatisk forhindrer oversettelse. For scenarioer der du vil forhindre lokalisering uten å bruke kodestil, kan du se ikke-lokaliserte strenger.