Jaa

Tekstin muotoiluohjeet

  • Artikkeli

Lihavoinnin, kursivoinnin ja koodityylin johdonmukainen ja asianmukainen käyttö tekstielementeissä parantaa luettavuutta ja auttaa välttämään väärinkäsityksiä.

Lihavoitu

Käytä lihavointia käyttöliittymän elementeissä, kuten valikkokohteissa, valintaikkunoiden nimissä ja syöttökenttien nimissä.

Esimerkit

  • Näin: Napsauta Ratkaisunhallinta-kohdassa hiiren kakkospainikkeella projektisolmua ja valitse sitten Lisää > uusi kohde.
  • Ei näin: Napsauta Ratkaisunhallinta-kohdassa hiiren kakkospainikkeella projektisolmua ja valitse sitten Lisää > uusi kohde.
  • Ei näin: Napsauta Ratkaisunhallinta-kohdassa hiiren kakkospainikkeella projektisolmua ja valitse sitten Lisää > uusi kohde.

Kursivointi

Käytä kursivointia seuraavissa kohteissa:

  • uusien termien esittely sekä määritelmät tai selitykset
  • tiedostojen ja kansioiden nimet sekä polut
  • käyttäjän syöte.

Esimerkit

  • Näin: sovelluspalvelu sovellus suoritetaan sovelluspalvelu-suunnitelmassa. Sovelluspalvelun suunnitelma määrittää käsittelyresurssien joukon, joissa verkkosovellus suoritetaan.
  • Ei näin: sovelluspalvelu sovellus suoritetaan sovelluspalvelu-suunnitelmassa. sovelluspalvelu määrittää käsittelyresurssien joukon, joissa verkkosovellus suoritetaan.
  • Näin: Korvaa HttpTriggerCSharp.cs koodi seuraavalla koodilla.
  • Ei näin: Korvaa kohdan HttpTriggerCSharp.cs koodi seuraavalla koodilla.
  • Näin: Kirjoita ContosoUniversity Nimi-kohtaan ja valitse sitten Lisää.
  • Ei näin: Kirjoita "ContosoUniversity" Nimi-kohtaan ja valitse sitten Lisää.

Koodityyli

Käytä koodityyliä seuraavissa kohteissa:

  • koodielementit, kuten menetelmien ja ominaisuuksien nimet sekä kielen avainsanat
  • SQL-komennot
  • NuGet-pakettien nimet
  • Komentorivikomennot*
  • tietokannan taulukkojen ja sarakkeiden nimet
  • resurssien nimet, joita ei saa lokalisoida (kuten näennäiskoneiden nimet)
  • URL-osoitteet, jos haluat, ettei niitä voi napsauttaa.

Miksi? Vanhemmissa tyylioppaissa neuvotaan käyttämään lihavointia monien tällaisten tekstielementtien kohdalla. Useimmat artikkelit kuitenkin lokalisoidaan, ja koodityyli kertoo kääntäjälle, että kyseistä tekstikohtaa ei käännetä.

Koodityyli voi olla tekstiin tekstiin sidottu (jota ympäröi ') tai aidatut koodilohkot ('), jotka ulottuvat useille riveille. Sijoita pidemmät koodikatkelmat ja polut aidattuihin koodilohkoihin.

* Käytä komentorivin komennoissa vinoviivoja tiedostopoluissa, jos niitä tuetaan kaikissa ympäristöissä. Käytä kenoviivaa havainnollistamaan Windowsissa suoritettavia komentoja, kun vain kenoviivat ovat tuettuja. Esimerkiksi vinoviivat toimivat .NET CLI:ssä kaikissa ympäristöissä, joten käyttäisit dotnet build foldername/filename.csproj -sovelluksen sijaan dotnet build foldername\filename.csproj.

Esimerkkejä tekstiin sidottujen tyylien käyttämisestä

  • Näin: Entity Framework tulkitsee oletusarvoisesti - tai ClassnameID -nimisen Id ominaisuuden perusavaimeksi.
  • Ei näin: Entity Framework tulkitsee oletusarvoisesti Id- tai ClassnameID-nimisen ominaisuuden perusavaimeksi.
  • Näin: - Microsoft.EntityFrameworkCore paketti tarjoaa suorituksenaikaisen tuen EF-ytimelle.
  • Ei näin: Microsoft.EntityFrameworkCore-paketti tarjoaa suorituksenaikaisen tuen EF-ytimelle.

Esimerkkejä aidatuista koodilohkoista

  • Näin: Tietokantaan ei lähetetä komentoja lausekkeilla, jotka vain muuttavat IQueryablekohdetta . Esimerkiksi seuraava koodi:

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

  • Ei näin: Tietokantaan ei lähetetä komentoja lausekkeilla, jotka vain muuttavat IQueryable-parametria, kuten var students = context. Students.Where(s => s.LastName == "Davolio").

  • Näin: Jos haluat esimerkiksi suorittaa Get-ServiceLog.ps1 -komentosarjan - C:\Scripts hakemistossa, kirjoita:

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

  • Ei näin: Jos haluat esimerkiksi suorittaa Get-ServiceLog.ps1-komentosarjan C:\Scripts-hakemistossa, kirjoita: "C:\Scripts\Get-ServiceLog.ps1."

  • Kaikissa aidatuissa koodilohkoissa on oltava hyväksytty kielitunniste. Luettelo tuetuista kielitunnisteista löytyy kohdasta Koodin sisällyttäminen asiakirjoihin.

Paikkamerkit

Jos haluat, että käyttäjä korvaa osan syötemerkkijonosta omilla arvoillaan, käytä paikkamerkkitekstiä, joka on merkitty kulmasulkeilla (vähemmän kuin < ja suurempi kuin > merkit).

Vaihtoehto 1: Käytä koodimuotoiluja paikkamerkkisanan tai kattavan lauseen ympäröimiseen. Voit esimerkiksi käyttää yksittäisiä grastiikkaa ' sisäisen koodin muotoiluun yksittäiselle lauseelle tai kolminkertaisia ""-jaksoja koodiaitattuun muotoiluun.

`az group delete -n <ResourceGroupName>`

Hahmontunut seuraavasti:

az group delete -n <ResourceGroupName>

or

Vaihtoehto 2: Käytä kenoviivaa \ , jos haluat välttää kulmasulkeen merkit Markdownissa, kuten \< ja \>. Vaikka vain ensimmäinen uloskäynti vasemmassa kulmasulkeessa \< on pakollinen, sulkevan hakasulkeen ohjauspainike \> toimii myös yhdenmukaisuuden vuoksi. Hahmontettu HTML ei näytä escape-merkkiä lukijalle:

az group delete -n \<ResourceGroupName\>

Hahmontunut seuraavasti:

az-ryhmän poistaminen -n <ResourceGroupName>

Ilmoita lukijalle paikkamerkistä: Selitä tällaisia paikkamerkkiesimerkkejä edeltävässä tekstissä lukijalle, että hakasulkeissa oleva teksti on poistettava ja korvattava todellisilla arvoilla. On suositeltavaa käyttää kursivointia käyttäjän syötteessä. Voit muotoilla kursivointia kulmasulkeen sisäisen koodin sisällä:

Korvaa seuraavassa esimerkissä paikkamerkkiteksti <ResourceGroupName> omalla resurssiryhmän nimellä.

Varoitus

Microsoft Learn -sivusto ei hahmonna <paikkamerkkitekstiä> , joka käyttää kulmasulkeita tapauksissa, joissa hakasulkeita ei ole käännetty oikein tai teksti ei ole koodimuotoista. Microsoft Learnin koontiprosessi tulkitsee <paikkamerkkilauseen> HTML-tunnisteeksi, joka voi olla vaarallinen lukijan selaimelle, ja merkitsee sen ei-sallittu-html-tunnisteeksi. Näet ehdotuksen koontiraportissa, eikä paikkamerkkisanaa hahmonneta Microsoft Learn -sivun tulosteessa, kun näin tapahtuu.

Jos haluat välttää sisällön menettämisen paikkamerkeissä, käytä code muotoilu- tai escape-merkkejä (\< \>) aiemmin kuvattujen ohjeiden mukaisesti.

Emme käytä aaltosulkeita { } syntaktisina paikkamerkkeinä. Lukijat voivat sekoittaa aaltosulkeiden paikkamerkit samaan merkintätapaan, jota käytetään:

  • Korvattava teksti
  • Muotoilumerkkijonot
  • Merkkijonojen interpolointi
  • Tekstimallit
  • Vastaavat ohjelmointirakennukset

Johdannaiset ja välistykset: Voit erottaa paikkamerkkien nimet yhdysmerkeillä ("kebab-kirjainkoko") tai alaviivoilla, tai voit tehdä sen käyttämällä Pascal-kirjainkokoa. Kebab-tapaus saattaa luoda syntaksivirheitä, ja alaviivat voivat olla ristiriidassa alleviivauksen kanssa. Kaikki enimmäisarvot voivat olla ristiriidassa nimettyjen vakioiden kanssa monilla kielillä, mutta se voi myös kiinnittää huomiota paikkamerkin nimeen.

<Resource-Group-Name> tai <ResourceGroupName>

Otsikot ja linkin teksti

Älä käytä tekstiin tekstiin rivin sisäistä tyyliä, kuten kursivointia tai lihavointia otsikoissa tai hyperlinkkitekstissä.

Miksi?

Tavallisten hyperlinkkitekstien oletetaan tunnistavan tekstielementit napsautettavina linkkeinä. Linkin muotoilu kursivoituna voi esimerkiksi peittää sen, että teksti on linkki. Otsikoissa on omat tyylinsä, ja muiden tyylien sekoittaminen ei näytä hyvältä.

Esimerkkejä otsikoista ja linkkitekstistä

  • Näin: function.json tiedosto luodaan NuGet-paketilla Microsoft.NET.Sdk.Functions.

  • Ei näin: function.json tiedosto luodaan NuGet-paketilla Microsoft.NET.Sdk.Functions.

  • Näin:

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

  • Ei näin:

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

Näppäimet ja pikanäppäimet

Kun viittaat näppäimiin tai näppäinyhdistelmiin, noudata seuraavia käytäntöjä:

  • Kirjoita näppäimen ensimmäinen kirjain isolla kirjaimella.
  • Ympäröi näppäinten nimet <kbd> ja </kbd> HTML-tunnisteet.
  • Käytä +-merkkiä liittääksesi avaimia, jotka käyttäjä valitsee samanaikaisesti.

Esimerkkejä näppäimiä ja pikanäppäimiä

  • Näin: Valitse Alt+Ctrl+S.
  • Ei näin: Paina ALT + CTRL + S.
  • Ei näin: Paina ALT+CTRL+S.

Poikkeukset

Tyyliohjeet eivät ole tiukkoja sääntöjä. Jos tyyli haittaa luettavuutta, muuta sitä. Esimerkiksi enimmäkseen koodielementtejä sisältävää HTML-taulukkoa voi olla vaikea lukea, jos siinä on käytetty paljon koodityyliä. Tässä yhteydessä lihavointi voi olla parempi vaihtoehto.

Jos valitset vaihtoehtoisen tekstityylin tilanteessa, jossa yleensä käytettäisiin koodia, varmista, että tekstin kääntämisestä ei ole haittaa artikkelin lokalisoiduissa versioissa. Koodi on ainoa tyyli, joka estää kääntämisen automaattisesti. Jos haluat estää lokalisoinnin koodityyliä käyttämättä, lisätietoja on ohjeaiheessa Lokalisoimattomat merkkijonot.