29

Это перевод. Оригинал - тут.

Недавно я сделал небольшой обзор вопросов, которые задают пользователи, и заметил, что большинство из них не пользуется внутристрочным выделением кода (например, «метод main()», или «класс HelloWorld») - другими словами, они не используют обратный апостроф (`).

Есть ли на SO страница или вопрос, на который можно отправить для объяснения, что такое выделение кода внутри строки и когда его стоит использовать (желательно с примерами)?

Я нашел вопрос Inline Code Spans should not be used for emphasis, right? (Верно ли, что выделение кода внутри строки нежелательно использовать для смысловых ударений?). К нему есть хороший ответ, в котором говорится, что внутристрочное выделение следует использовать для «кода и кодообразных сущностей». Однако, тот вопрос приводит нас к другому вопросу - что такое «кодообразная сущность». Например, идентификаторы или фрагменты логов часто форматируют при помощи внутристрочного выделения, но их с трудом можно назвать «кодообразными сущностями». Можно привести и другие примеры, которые еще больше запутают дело.

Во многих изданиях по программированию имеется раздел, в котором приводится описание того, как и для чего в книге применяются то или иное форматирование текста. Есть ли на SO похожее описание относительно использования внутристрочного выделения кода?

6
  • 1
    Замечу, что на русском, использовать символ ` неудобно, т.к. он в английской раскладке.
    – Kromster
    Commented 18 сент. 2015 в 7:50
  • 9
    @KromStern выделяете блок текста и Ctrl + K.
    – Nick Volynkin Мод
    Commented 18 сент. 2015 в 10:45
  • @NickVolynkin класс, спасибо!
    – Kromster
    Commented 18 сент. 2015 в 10:52
  • Добавил этот вопрос в Часто задаваемые вопросы о StackOverflow
    – Nick Volynkin Мод
    Commented 21 сент. 2015 в 8:02
  • 2
    @KromStern Проблем с апострофом у меня не возникло ни разу, поскольку код также в английской раскладке — всё равно переключаться. Commented 21 сент. 2015 в 12:12
  • @MarkShevchenko код часто копипастой вставляется
    – Kromster
    Commented 21 сент. 2015 в 12:37

2 ответа 2

32

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

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

Для элементов пользовательского интерфейса гораздо лучше подходит подходит html-тег <kbd>...</kbd>. Например:

Для того, чтобы сохранить файл под новым именем, щелкните Файл > Сохранить как..., либо Ctrl ShiftS ( Cmd ⌘ Shift ⇧ S )

Идентификаторы или фрагменты логов

Довольно часто имеют строки очень большой длины и обычно предназначены для чтения человеком. Поэтому для них отлично подходит форматирование цитатой («>» перед строкой).

Сравните с кодом:

Довольно часто имеют строки очень большой длины и обычно предназначены для чтения человеком. Поэтому для них отлично подходит форматирование цитатой («>» перед строкой).

Довольно часто имеют строки очень большой длины и обычно предназначены для чтения человеком. Поэтому для них отлично подходит форматирование цитатой («>» перед строкой).

Названия IDE, библиотек, плагинов, инструментов

Плохо:

Для программирования под Android удобно использовать Android Studio.

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

Хорошо:

Для широко известных инструментов (когда есть этого инструмента) — ничего. Их и так все знают.

При желании, вы можете использовать курсив (спасибо pavlofff за подсказку), но только в своих сообщениях. Курсив воспринимается как расстановка акцентов в тексте; добавлять курсив в чужие сообщения не стоит.

Для программирования под андроид удобно использовать Android Studio.

Для менее известных (когда нет метки) – ссылка! Лучший способ выделить название библиотеки foobar с гитхаба — дать ссылку точно на тот репозиторий, с которого вы ее взяли, указав также имя автора. Вот так:

Использовал плагин iwhitcomb/foobar.

Название языка, на котором у вас код в вопросе

Плохо:

Написал вот такой вот код на языке javascript...

Хорошо: метка на вопросе (не в тексте вопроса, а в специальном поле для меток).

Ссылки

Хорошо: ссылка, ссылка, ссылка. Опять же, в чужие сообщения не нужно добавлять курсив и полужирный шрифт. Пусть автор сам решает, на что обращать внимание читателя.

Плохо: ссылка, но нормально как код в ссылке: ссылка на документацию по printf

6
  • Подскажите pavlofff это обычная ссылка? или есть какие-нибудь отдельные способы для ссылок на профиле пользователей сайта?
    – 4per
    Commented 30 сент. 2016 в 12:26
  • В предыдущим комментарии (да и в этом тоже) я использовал выделение кодом для не кода. Какие существуют правила хорошего тона при оформлении комментариев?
    – 4per
    Commented 30 сент. 2016 в 12:28
  • @4per 1) да, это обычная ссылка, сокращённого синтаксиса нет. 2) В основном всё то же самое, т.е. код или результат работы кода. Я ещё цитируемые сообщения выделяю так, но это личная инициатива.
    – Nick Volynkin Мод
    Commented 30 сент. 2016 в 13:33
  • Почему плохо выделять названия IDE, библиотек, плагинов, инструментов и мелких участков кода (таких как тип данных) - кодом? А не для этого ли придуман символ «`», чтобы в тексте выделять мелкие внутристрочные блоки? Commented 28 нояб. 2016 в 14:02
  • @DenisBubnov мелкие участки кода именно так и нужно выделять, внутристрочное форматирование кода придумано именно для них. Остальное — плохо, потому что появляется конфликт (несоответствие) формы и содержания. Это как синий с подчёркиванием шрифт, который не является ссылкой или как изображение кнопки, которое не является кнопкой. Как баннеры, которые с помощью оформления маскируются под основное содержимое сайта. Как кнопка «Скачать», которая открывает три рекламных страницы, а скачать не даёт. В общем, плохо и вызывает ненависть пользователей. ))
    – Nick Volynkin Мод
    Commented 28 нояб. 2016 в 14:38
  • @DenisBubnov а конфликт появляется потому, что мы привыкли, что код на сайте выглядит совершенно определённым образом, а остальное выглядит иначе. И когда мы видим код, включается внутренний парсер/интерпретатор/компилятор. И сразу выдаёт ошибку: class Android Studio not found.
    – Nick Volynkin Мод
    Commented 28 нояб. 2016 в 14:41
15

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

Для чего следует использовать внутристрочное выделение

Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На SO есть единственный способ это сделать (применить внутристрочное выделение кода) — поэтому я использую выделение для подсветки таких строк, когда пишу на SO. В документах для личного пользования, я делаю обычно только одно исключение — использую отдельный стиль оформления текста для выделения элементов пользовательского интерфейса (например, "ФайлОткрыть…").

Когда внутристрочное выделение использовать не стоит

Строки, которые используются в документах, предназначенных для чтения человеком (например: торговые марки, названия пакетов программ, сами программы, библиотеки, технологии, аббревиатуры) — не выделяются как код, для них должен применяться другой стиль. Например HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

О строках, которые обрабатываются или генерируются компьютером

  • небольшие фрагменты листингов (например, SELECT * FROM MyTable, this.id =id;)
  • имена классов, методов, блоков, переменных, параметров методов, строковые константы, имена файлов, пути к файлам, расширения файлов, теги HTML, предложения SQL, фрагменты конфигурационных файлов и тому подобное
  • входные данные программ (например, значения, вводимые пользователем)
  • вывод программ (фрагмент вывода на терминал, фрагмент лога)

Двойственные случаи

Имеются некоторые случаи двойственности: "gedit", — это имя популярного редактора текстов, а также команда, которая этот редактор запускает. Как имя программы, это слово НЕ СЛЕДУЕТ выделять, но как команду, интерпретируемую компьютером, следует. Возможно, форматирование следует выбирать в соответствии с контекстом употребления слова.

О других соглашениях о форматировании

В литературе по программированию часто содержится раздел, который объясняет, каким образом в книге используются те или иные стили текста. Эти соглашения являются более подробными, нежели те, что здесь приведены. Например, для пользовательского ввода и вывода программ могут использоваться отдельные стили. Однако, на SO нет таких возможностей оформления, чтобы удовлетворить такие широкие потребности. Кроме того, написание постов с использованием большого количества стилей, может оказаться трудоемким.

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

Множество книг используют отдельный стиль текста для выделения таких элементов. Напрмер, "Выделите пункт Сохранить Как… в меню Файл." или Щелкните "ФайлСохранить как…" Возможно, в случае SO, элементы интерфейса также стоит выделять при помощи внутристрочного выделения для кода.

Использование кавычек

Нет необходимости помещать фрагменты кода в дополнительные кавычки — они уже и так выделены. Однако, для строковых констант следует сделать исключение и приводить их вместе с разграничителями. Например: "Метод sayHello() возвращает "Hello World!"."

Примеры

Java (тексты примеров взяты из официальной документации http://docs.oracle.com/)

  • Конвертация в строку осуществляется методом toString, который объявлен в Object и наследуется всеми классами Java.
  • Если не указано иное, передача null в качестве аргумента конструктора или метода вызовет выбрасывание исключения NullPointerException.
0

Войдите, чтобы ответить на этот вопрос.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками .