Поделиться через

Рекомендации по форматированию текста

  • Статья

Согласованное и надлежащее использование полужирного шрифта, курсива и кода для фрагментов текста повышает удобочитаемость и помогает избежать недопонимания.

Жирный

Используйте полужирный шрифт для элементов пользовательского интерфейса, таких как списки выбора меню, названия диалоговых окон и имена полей ввода.

Примеры

  • Правильно. В Обозревателе решений щелкните правой кнопкой мыши узел проекта и выберите Добавить > Новый элемент.
  • Неправильно. В Обозревателе решений щелкните правой кнопкой мыши узел проекта и выберите "Добавить" > "Новый элемент".
  • Неправильно. В Обозревателе решений щелкните правой кнопкой мыши узел проекта и выберите Добавить > Новый элемент.

Курсив

Используйте курсив для следующих элементов:

  • новые термины, которые вы вводите с определением или объяснением;
  • имена файлов и папок, пути.
  • ввод данных пользователем.

Примеры

  • Правильно. В службе приложений приложение запускается в плане службы приложений. План службы приложений — это набор вычислительных ресурсов, с которыми запускается веб-приложение.
  • Неправильно. В Службе приложений приложение выполняется в плане службы приложений, который определяет набор вычислительных ресурсов для запуска веб-приложения.
  • Это: замените код в HttpTriggerCSharp.cs следующим кодом.
  • Неправильно. Замените код в HttpTriggerCSharp.cs следующим кодом.
  • Введите ContosoUniversity для имени и нажмите кнопку "Добавить".
  • Не так: введите "ContosoUniversity" для имени, а затем нажмите кнопку "Добавить".

Стиль кода

Используйте стиль кода для следующих элементов:

  • элементы кода, такие как имена методов, имена свойств и ключевые слова;
  • Команды SQL
  • имена пакетов NuGet;
  • команды командной строки*;
  • имена таблиц и столбцов базы данных;
  • имена ресурсов, которые не должны быть локализованы (например, имена виртуальных машин);
  • URL-адреса, которые вы не хотите делать активными.

Почему? В старых руководствах по стилям для многих из этих текстовых элементов рекомендуется полужирный шрифт. Но большинство статей переводятся, и стиль кода требует от переводчика оставлять эту часть текста неизменной.

Стиль кода может быть встроенным (заключенным в `) или изолированным блоком кода (заключенным в ```), состоящим из нескольких строк. В отдельные блоки кода следует помещать более длинные фрагменты кода.

* В командах командной строки используйте косую черту в путях к файлам, если это поддерживается на всех платформах. Используйте обратную косую черту, чтобы обозначить команды, выполняемые в Windows, если поддерживается только этот символ. Например, косая черта поддерживается в .NET CLI на всех платформах, поэтому вместо dotnet build foldername/filename.csproj следует использовать dotnet build foldername\filename.csproj.

Примеры с использованием встроенных стилей

  • Правильно. По умолчанию Entity Framework интерпретирует свойство с именем Id или ClassnameID как первичный ключ.
  • Неправильно. По умолчанию Entity Framework интерпретирует свойство с именем Id или ClassnameID как первичный ключ.
  • Правильно. Пакет Microsoft.EntityFrameworkCore предоставляет поддержку среды выполнения для EF Core.
  • Неправильно. Пакет Microsoft.EntityFrameworkCore предоставляет поддержку среды выполнения для EF Core.

Примеры отдельных блоков кода

  • Правильно. Операторы, которые просто меняют IQueryable, как в следующем коде, не отправляют команды в базу данных.

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

  • Неправильно. Операторы, которые просто меняют IQueryable, как в коде var students = context.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."

  • Все огороженные блоки кода должны иметь утвержденный тег языка. Список поддерживаемых тегов языка см. в разделе Как включить код в документацию.

Заполнители

Если вы хотите, чтобы пользователь заменил часть входной строки собственными значениями, используйте текст-заполнитель, отмеченный угловыми скобками (меньше < и больше > символов).

Вариант 1. Используйте стили кода, чтобы окружить слово-заполнитель или охватывающую фразу. Например, вы можете использовать одиночные обратные кавычки `для форматирования встроенного кода для одной фразы или тройные кавычки `` для форматирования изолированного кода.

`az group delete -n <ResourceGroupName>`

Отображение:

az group delete -n <ResourceGroupName>

or

Вариант 2. Используйте обратную косую черту \, чтобы экранировать символы угловых скобок в Markdown, такие как \< и \>. Хотя требуется экранировать только левую угловую скобку \<, экранирование закрывающей скобки \> также полезно для обеспечения единообразия. Отображенный код HTML не отображает escape-символ для читателя:

az group delete -n \<ResourceGroupName\>

Отображение:

az group delete -n <ResourceGroupName>

Сообщите читателю о заполнителе. В тексте, предшествующем таким примерам заполнителя, объясните читателю, что текст в скобках должен быть удален и заменен реальными значениями. Для вводимых пользователем данных рекомендуется использовать курсив. Можно отформатировать курсив в пределах встроенного кода в угловых скобках:

В следующем примере замените текст заполнителя <ResourceGroupName> именем своей группы ресурсов.

Внимание

Сайт Microsoft Learn не отображает <текст заполнителя> , использующий угловые скобки в случаях, когда квадратные скобки не экранируются должным образом или текст не форматируется кодом. Процесс сборки Microsoft Learn интерпретирует <фразу заполнителя> как HTML-тег, который может быть опасным для браузера читателя, и помечает его как запрещенный html-тег. Вы увидите предложение в отчете о сборке, а заполнитель не отображается в выходных данных страницы Microsoft Learn, когда это происходит.

Чтобы избежать потери содержимого для заполнителей, используйте code форматирование или escape-символы (\<\>), как описано ранее.

Мы не рекомендуем использовать фигурные скобки {} в качестве синтаксических заполнителей. Читатели могут перепутать заполнители фигурных скобок с обозначениями, используемыми в:

  • заменяемом тексте;
  • Строки формата
  • Интерполяция строк
  • текстовых шаблонах;
  • сходных конструкциях программирования.

Регистр и пробелы. Вы можете разделять имена заполнителей дефисами (kebab-case) или подчеркиванием, или вы можете сделать это, используя Pascal case. Kebab-case может вызывать синтаксические ошибки, а знаки подчеркивания могут конфликтовать с подчеркиванием. Использование всех заглавных букв может вызвать конфликты с именованными константами во многих языках, хотя такой текст также может привлекать внимание к имени заполнителя.

<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

Клавиши и сочетания клавиш

При упоминании клавиш или сочетаний клавиш следуйте приведенным ниже соглашениям.

  • Название клавиши должно быть написано прописными буквами.
  • Заключите имена клавиш в HTML-теги <kbd> и </kbd>.
  • Используйте "+" для объединения клавиш, которые пользователь должен нажать одновременно.

Примеры клавиш и сочетаний клавиш

  • Правильно. Нажмите клавиши ALT+CTRL+S.
  • Не так: нажмите клавиши ALT+CTRL+S.
  • Неправильно. Нажмите клавиши ALT+CTRL+S.

Исключения

Рекомендации по стилю не являются строгими правилами. Если при их соблюдении текст будет плохо читаться, выберите другой вариант. Например, таблица HTML со множеством элементов кода может выглядеть перегруженной, если везде применять стилизацию кода. В этом контексте вы можете выбрать полужирный стиль.

Если выбран альтернативный стиль текста там, где должен быть код, убедитесь, что текст можно будет перевести на другие языки. Код — это единственный стиль, который автоматически препятствует переводу. Если вы хотите предотвратить локализацию без использования стиля кода, см. раздел Нелокализованные строки.