Так как никто не привел никаких существующих соглашений об использовании внутристрочного выделения кода, я решил опубликовать собственное решение. Оно является моим личным мнением и обобщает мой опыт. Надеюсь, что оно окажется полезным.
Для чего следует использовать внутристрочное выделение
Любая строка, которая обрабатывается или генерируется компьютером, обычно должна быть выделена в тексте. На 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
.