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

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

• Форматирование общих текстовых элементов

• Форматирование текста в инструкциях

• Форматирование общих для разработчиков элементов

Элементы пользовательского интерфейса

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

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

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

Имена репозитория и ветви Git

Используйте полужирный текст для имен репозитория или ветви Git при выборе или вводе в инструкции.

• Следующее: В меню ветви выберите main.

• Не так: В меню ветви выберите "main".

Новые введение терминов

Используйте курсивный текст, чтобы ввести новый термин вместе с определением или объяснением. Курсивируйте новый термин при первом использовании, а затем используйте обычный текст для определения или объяснения.

• Правильно. В службе приложений приложение запускается в плане службы приложений. План службы приложений — это набор вычислительных ресурсов, с которыми запускается веб-приложение.

• Неправильно. В Службе приложений приложение выполняется в плане службы приложений, который определяет набор вычислительных ресурсов для запуска веб-приложения.

Стиль кода

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

• элементы кода, такие как имена методов, имена свойств и ключевые слова;
• Команды 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."

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

Заполнители

В тексте абзаца или процедурных шагах используйте курсив для замещающего текста, который пользователи заменят собственными сведениями.

• Это: введите пароль

• Не так: введите "пароль"

• Это: Введите -pпароль

• Не так: введите пароль -p

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

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

`az group delete -n <ResourceGroupName>`

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

az group delete -n <ResourceGroupName>

или

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

az group delete -n \<ResourceGroupName\>

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

az group delete -n <ResourceGroupName>

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

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

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

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

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

<Resource-Group-Name> или <ResourceGroupName>

Заголовки

Не применяйте встроенные стили, такие как курсив, полужирный или стиль кода, к заголовкам.

Почему? Заголовки имеют собственные стили, а сочетание других стилей создает несоответствия.

• Это: импорт пакета Microsoft.NET.Sdk.Functions

• Не так: импортируйте пакет Microsoft.NET.Sdk.Functions

Текст ссылки

Не применяйте встроенные стили, такие как курсив или полужирный, к тексту ссылки.

Почему? Читатели ожидают стандартный текст гиперссылок, чтобы определить текстовые элементы как активные ссылки. Стилизация ссылки как курсив, например, может скрыть тот факт, что текст является ссылкой.

• Это: пакет NuGet Microsoft.NET.Sdk.Functions создает файл function.json.

Не так: пакет NuGet Microsoft.NET.Sdk.Functions создает файл function.json.

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

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

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

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

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

Исключения

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

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