Κοινή χρήση μέσω

Οδηγίες μορφοποίησης κειμένου

  • Άρθρο

Η συνεπής και κατάλληλη χρήση έντονης γραφής, πλάγιας γραφής και στυλ κώδικα για στοιχεία κειμένου βελτιώνει την αναγνωσιμότητα και συμβάλει στην αποφυγή παρανοήσεων.

Bold

Χρησιμοποιήστε έντονη γραφή για στοιχεία περιβάλλοντος εργασίας χρήστη, όπως οι επιλογές μενού, τα ονόματα παραθύρων διαλόγου και τα ονόματα πεδίων εισόδου.

Παραδείγματα

  • Σωστό: Στην Εξερεύνηση λύσεων, κάντε δεξί κλικ στον κόμβο έργου και, στη συνέχεια, επιλέξτε Προσθήκη > νέου στοιχείου.
  • Λάθος: Στην Εξερεύνηση λύσεων, κάντε δεξί κλικ στον κόμβο έργου και, στη συνέχεια, επιλέξτε Προσθήκη > νέου στοιχείου.
  • Λάθος: Στην Εξερεύνηση λύσεων, κάντε δεξί κλικ στον κόμβο έργου και, στη συνέχεια, επιλέξτε Προσθήκη > νέου στοιχείου.

Πλάγια

Χρησιμοποιήστε πλάγια γραφή για:

  • Εισαγωγή νέων όρων μαζί με έναν ορισμό ή μια εξήγηση.
  • Ονόματα αρχείων, ονόματα φακέλων, διαδρομές.
  • Στοιχεία που εισάγονται από τον χρήστη.

Παραδείγματα

  • Σωστό: Στο App Service, μια εφαρμογή εκτελείται σε ένα πρόγραμμα App Service. Ένα πρόγραμμα App Service ορίζει ένα σύνολο υπολογιστικών πόρων βάσει του οποίου εκτελείται μια εφαρμογή web.
  • Λάθος: Στο App Service, μια εφαρμογή εκτελείται σε ένα "Πρόγραμμα υπηρεσίας εφαρμογής". Ένα πρόγραμμα App Service ορίζει ένα σύνολο υπολογιστικών πόρων σύμφωνα με τις οποίες εκτελείται μια εφαρμογή web.
  • Σωστό: Αντικαταστήστε τον κώδικα στο HttpTriggerCSharp.cs με τον ακόλουθο κώδικα.
  • Λάθος: Αντικαταστήστε τον κώδικα στο HttpTriggerCSharp.cs με τον ακόλουθο κώδικα.
  • Σωστό: Εισαγάγετε ContosoUniversity για το Όνομα και, στη συνέχεια, επιλέξτε Προσθήκη.
  • Λάθος: Πληκτρολογήστε "ContosoUniversity" για το Όνομα και, στη συνέχεια, επιλέξτε Προσθήκη.

Στυλ κώδικα

Χρησιμοποιήστε στυλ κώδικα για:

  • Στοιχεία κώδικα, όπως ονόματα μεθόδων, ονόματα ιδιοτήτων και λέξεις-κλειδιά γλωσσών.
  • Εντολές SQL
  • Ονόματα πακέτου NuGet
  • Εντολές γραμμής εντολών*
  • Ονόματα πινάκων δεδομένων και στηλών
  • Ονόματα πόρων που δεν θα πρέπει να μεταφράζονται (όπως ονόματα εικονικών μηχανών)
  • Διευθύνσεις URL οι οποίες δεν θέλετε να έχουν δυνατότητα κλικ

Γιατί; Οι παλαιότεροι οδηγοί στυλ ορίζουν έντονη γραφή για πολλά από αυτά τα στοιχεία κειμένου. Ωστόσο, τα περισσότερα άρθρα έχουν μεταφραστεί και το στυλ κώδικα υποδεικνύει στον μεταφραστή να αφήσει αυτό το τμήμα του κειμένου αμετάφραστο.

Το στυλ κώδικα μπορεί να είναι ενσωματωμένο (που περικλείεται από ') ή περίφρακτα στοιχεία επιπέδου μπλοκ κώδικα (που περιβάλλονται από ''') που εκτείνονται σε πολλές γραμμές. Τοποθετήστε τμήματα κώδικα και διαδρομές μεγαλύτερου μήκους σε περίφρακτα στοιχεία επιπέδου μπλοκ κώδικα.

* Στις εντολές γραμμής εντολών, χρησιμοποιήστε καθέτους στις διαδρομές αρχείων, εάν υποστηρίζονται σε όλες τις πλατφόρμες. Χρησιμοποιήστε ανάστροφες καθέτους για να απεικονίστε εντολές που εκτελούνται στα Windows, όταν υποστηρίζονται μόνο ανάστροφες καθέτους. Για παράδειγμα, οι καθέτους λειτουργούν στο .NET CLI σε όλες τις πλατφόρμες, ώστε να χρησιμοποιήσετε dotnet build foldername/filename.csproj αντί για dotnet build foldername\filename.csproj.

Παραδείγματα που χρησιμοποιούν ενσωματωμένα στυλ

  • Σωστό: Από προεπιλογή, το Πλαίσιο οντοτήτων ερμηνεύει μια ιδιότητα που ονομάζεται Id ή ClassnameID ως πρωτεύον κλειδί.
  • Λάθος: Από προεπιλογή, το Πλαίσιο οντοτήτων ερμηνεύει μια ιδιότητα που ονομάζεται Id ή ClassnameID ως πρωτεύον κλειδί.
  • Σωστό: Το Microsoft.EntityFrameworkCore πακέτο παρέχει υποστήριξη χρόνου εκτέλεσης για πυρήνα ΟΕ.
  • Λάθος: Το πακέτο Microsoft.EntityFrameworkCore παρέχει υποστήριξη χρόνου εκτέλεσης για πυρήνα EF.

Παραδείγματα περίφρακτων στοιχείων επιπέδου μπλοκ κώδικα

  • Σωστό: Δεν αποστέλλονται εντολές στη βάση δεδομένων με προτάσεις που απλώς αλλάζουν μια IQueryable, όπως τον ακόλουθο κώδικα:

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

  • Λάθος: Δεν αποστέλλονται εντολές στη βάση δεδομένων με προτάσεις που απλώς αλλάζουν ένα IQueryable, όπως var students = περιβάλλον. Students.Where(s => s.LastName == "Davolio").

  • Σωστό: Για παράδειγμα, για να εκτελέσετε τη Get-ServiceLog.ps1 δέσμη ενεργειών στον C:\Scripts κατάλογο, πληκτρολογήστε:

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

  • Λάθος: Για παράδειγμα, για να εκτελέσετε τη δέσμη ενεργειών Get-ServiceLog.ps1 στον κατάλογο C:\Scripts, πληκτρολογήστε: "C:\Scripts\Get-ServiceLog.ps1.ps1."

  • Όλα τα περίφρακτα στοιχεία επιπέδου μπλοκ κώδικα πρέπει να έχουν εγκεκριμένη ετικέτα γλώσσας. Για μια λίστα με τις ετικέτες γλωσσών υποστήριξης, ανατρέξτε στο θέμα Πώς μπορείτε να συμπεριλάβετε κώδικα σε έγγραφα.

Χαρακτήρες κράτησης θέσης

Εάν θέλετε ο χρήστης να αντικαταστήσει μέρος μιας συμβολοσειράς εισόδου με τις δικές του τιμές, χρησιμοποιήστε κείμενο κράτησης θέσης που έχει επισημανθεί με γωνιακές αγκύλες (μικρότερο και < μεγαλύτερο από > τους χαρακτήρες).

Επιλογή 1: Χρησιμοποιήστε στυλ κώδικα για να περικλείετε τη λέξη κράτησης θέσης ή τη φράση που περιλαμβάνει. Για παράδειγμα, μπορείτε να χρησιμοποιήσετε μονά βαρείες ' για μορφοποίηση ενσωματωμένου κώδικα για μία μόνο φράση ή τριπλά σήματα ρολογιού ''' για μορφοποίηση με περίφρακτο κώδικα.

`az group delete -n <ResourceGroupName>`

Αποδίδεται ως:

az group delete -n <ResourceGroupName>

ή

Επιλογή 2: Χρησιμοποιήστε έναν χαρακτήρα \ ανάστροφης κάθετος για να ξεφύγετε από τους χαρακτήρες γωνιακής αγκύλης στο Markdown, όπως \< και \>. Παρόλο που απαιτείται μόνο η πρώτη διαφυγή στην αριστερή γωνία αγκύλης \< , η διαφυγή από τη δεξιά αγκύλη \> λειτουργεί επίσης για λόγους συνέπειας. Η HTML που αποδίδεται δεν εμφανίζει τον χαρακτήρα διαφυγής στον αναγνώστη:

az group delete -n \<ResourceGroupName\>

Αποδίδεται ως:

az group delete -n <ResourceGroupName>

Ενημερώστε τον αναγνώστη σχετικά με το σύμβολο κράτησης θέσης: Στο κείμενο που προηγείται αυτών των παραδειγμάτων κράτησης θέσης, εξηγήστε στον αναγνώστη ότι το κείμενο στις αγκύλες πρέπει να καταργηθεί και να αντικατασταθεί με πραγματικές τιμές. Συνιστούμε τη χρήση πλάγιας γραφής για εισαγωγή από τον χρήστη. Μπορείτε να μορφοποιήσετε πλάγια γραφή μέσα σε ενσωματωμένο κώδικα με γωνιακή αγκύλη:

Στο παρακάτω παράδειγμα, αντικαταστήστε το κείμενο <ResourceGroupName> κράτησης θέσης με το δικό σας όνομα ομάδας πόρων.

Προσοχή

Η τοποθεσία του Microsoft Learn δεν αποδίδει <κείμενο κράτησης θέσης> που χρησιμοποιεί γωνιακές αγκύλες σε περιπτώσεις όπου οι αγκύλες δεν έχουν τη σωστή διαφυγή ή το κείμενο δεν έχει μορφοποίηση κώδικα. Η διαδικασία δόμησης του Microsoft Learn ερμηνεύει τη <φράση κράτησης θέσης> ως ετικέτα HTML που θα μπορούσε να είναι επικίνδυνη για το πρόγραμμα περιήγησης του αναγνώστη και την επισημαίνει ως ετικέτα που δεν επιτρέπεται. Θα δείτε μια πρόταση στην αναφορά δόμησης και η λέξη κράτησης θέσης δεν αποδίδεται στην έξοδο σελίδας του Microsoft Learn όταν συμβαίνει αυτό.

Για να αποφύγετε απώλεια περιεχομένου σε σύμβολα κράτησης θέσης, χρησιμοποιήστε code μορφοποίηση ή χαρακτήρες διαφυγής (\< \>) όπως περιγράφεται προηγουμένως.

Δεν συνιστάται η χρήση άγκιστρα { } ως συμβάματα κράτησης θέσης. Οι αναγνώστες μπορούν να συγχέουν τα σύμβολα κράτησης θέσης άγκιστρας με την ίδια σημειογραφία που χρησιμοποιείται:

  • Κείμενο με δυνατότητα αντικατάστασης
  • Συμβολοσειρές μορφοποίησης
  • Διακοπή συμβολοσειράς
  • Πρότυπα κειμένου
  • Παρόμοιες κατασκευές προγραμματισμού

Περίβλημα και διαστήματα: Μπορείτε να διαχωρίσετε τα ονόματα συμβόλων κράτησης θέσης με ενωτικά ("υπόθεση κεμπάπ") ή με χαρακτήρες υπογράμμισης ή μπορείτε να το κάνετε χρησιμοποιώντας πεζά-κεφαλαία κατά Pascal. Η υπόθεση κεμπάπ μπορεί να δημιουργήσει σφάλματα σύνταξης και οι χαρακτήρες υπογράμμισης μπορεί να έρχονται σε διένεξη με υπογράμμιση. Τα κεφαλαία ενδέχεται να έρχονται σε διένεξη με επώνυμες σταθερές σε πολλές γλώσσες, παρόλο που μπορεί επίσης να τραβήξει την προσοχή στο όνομα κράτησης θέσης.

<Resource-Group-Name> ή <ResourceGroupName>

Επικεφαλίδες και κείμενο σύνδεσης

Μην εφαρμόζετε ενσωματωμένο στυλ, όπως πλάγια γραφή ή έντονη γραφή σε κεφαλίδες ή κείμενο υπερ-σύνδεσης.

Γιατί;

Οι χρήστες βασίζονται σε τυπικό κείμενο υπερ-σύνδεσης, για να προσδιορίσουν στοιχεία κειμένου ως συνδέσεις με δυνατότητα κλικ. Στυλ μιας σύνδεσης ως πλάγια γραφή, για παράδειγμα, μπορεί να αποκρύψει το γεγονός ότι το κείμενο είναι σύνδεση. Οι επικεφαλίδες έχουν τα δικά τους στυλ και η ανάμειξη άλλων στυλ σε αυτές δεν φαίνεται ωραία.

Παραδείγματα κεφαλίδων και κειμένου σύνδεσης

  • Σωστό: Το αρχείο function.json δημιουργείται από το πακέτο NuGet Microsoft.NET.Sdk.Functions.

  • Λάθος: Το αρχείο function.json δημιουργείται από το πακέτο NuGet Microsoft.NET.Sdk.Functions.

  • Σωστό:

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

  • Λάθος:

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

Πλήκτρα και συντομεύσεις πληκτρολογίου

Όταν αναφέρεστε σε πλήκτρα ή συνδυασμούς πλήκτρων, ακολουθήστε αυτές τις συμβάσεις:

  • Χρησιμοποιήστε κεφαλαία για το πρώτο γράμμα των ονομάτων πλήκτρων.
  • Περικλεώστε τα ονόματα κλειδιών με <kbd> ετικέτες ΚΑΙ </kbd> ετικέτες HTML.
  • Χρησιμοποιήστε το "+" για να ενώσετε κλειδιά που επιλέγει ταυτόχρονα ο χρήστης.

Παραδείγματα πλήκτρων και συντομεύσεων πληκτρολογίου

  • Σωστό: Επιλέξτε Alt+Ctrl+S.
  • Λάθος: Πατήστε ALT+CTRL+S.
  • Λάθος: Πατήστε ALT+CTRL+S.

Εξαιρέσεις

Οι οδηγίες στυλ δεν είναι αυστηροί κανόνες. Σε περιβάλλοντα όπου βλάπτουν την αναγνωσιμότητα, κάντε κάτι διαφορετικό. Για παράδειγμα, ένας πίνακας HTML με κυρίως στοιχεία κώδικα μπορεί να φαίνεται υπερβολικά φορτωμένος με στυλ κώδικα παντού. Μπορείτε να επιλέξετε στυλ έντονης γραφής σε αυτό το περιβάλλον.

Εάν επιλέξετε ένα εναλλακτικό στυλ κειμένου στο οποίο απαιτείται κανονικά κώδικας, βεβαιωθείτε ότι δεν πειράζει το κείμενο να μεταφραστεί σε μεταφρασμένες εκδόσεις του άρθρου. Ο κώδικας είναι το μόνο στυλ που αποτρέπει αυτόματα τη μετάφραση. Για τα σενάρια στα οποία θέλετε να αποτρέψετε την τοπική προσαρμογή χωρίς τη χρήση στυλ κώδικα, ανατρέξτε στην ενότητα Μη μεταφρασμένες συμβολοσειρές.