Правил написания инлайнового кода

[pepelsbey]

Код можно писать двумя способами.

Блоками

```css
body {
  font-family: sans-serif;
}
```

body {
  font-family: sans-serif;
}

Инлайном

Чтобы сделать красиво, добавьте `font-family: sans-serif`.

Чтобы сделать красиво, добавьте font-family: sans-serif.

Как у нас сейчас

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

• Клавиатурных сокращений Ctrl C — мы с этим справились, теперь нужно делать <kbd>Ctrl C</kbd>
• Названий файлов: откройте package.json или пакетов установите npm
• Любых других ситуаций, в которых хочется выделение

В чём проблема

Бэктики в маркдауне рендерятся в тег <code>, который уместен только для примеров кода. Нам стоит обсудить, в каких ситуациях его уместно. В целом, всё просто: для примеров кода :) Занавес.

Но было бы хорошо рекомендовать какое ещё выделение использовать. Или привести побольше примеров.

[bespoyasov]

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

Но даже, если мы решим, что нет и не будем использовать тег code, думаю, стоит оставить такой же стиль, как у кода. Когда я читаю инструкцию, я её сканирую глазами, вылепляя ключевые слова. Курсив и жирный ощущаются, как выделение, но в «другом контексте», как будто это важно, но не «то, что мне нужно вот прям сейчас».

В остальных местах обычно использую курсив, чтобы было заметно в строке, и жирный, чтобы было заметно в параграфе.

[pepelsbey]

это тоже программные сущности

К сожалению, это слабо формализовано и все будут считать такими сущностями какие-то свои слова. Ну либо нам придётся стартовать собственную школу обозначения терминов, описать её и форсить. На мой взгляд, проще договориться, что если это тег, свойство, метод или прямая цитата из кода — это код. А всё остальное — просто название.

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

Например, из новых для нас: mark, b, i, samp, dfn или уже используемые code, kbd.

[nlopin]

Классно использовать семантические теги, но как это контролировать? Если очень повезёт, то на ревью мы отловим все случаи неверного использования, но пропустить неверное использование очень легко.

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

[pepelsbey]

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

А в общем случае есть два простых сценария:

1. <code> для кода и остальное — просто слова с любым стандартным выделением. Пишется понятная документация, проводится контроль на ревью.
2. <code> для всего, что автору захочется выделить, без документации и контроля на ревью.

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

[nlopin]

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

Мне предложение <code> для кода нравится, но нужно предложить альтеративу для штук вокруг кода. Курсив? Моноширинный шрифт?

[solarrust]

Курсив и моноширинный шрифт — это внешнее оформление. Нам нужно подобрать семантичный тег. А стили ему можно задать любые. Проблема в том, что мы вроде как старались уйти от HTML в Маркдаунах максимально. Внешним контрибьютерам, кажется, это будет не так принципиально как нам. Значит повышается нагрузка на ревьюера и редактора, которые должны будут расставить правильные теги в нужных местах. В принципе, мы справимся, конечно, но жить становится сложнее =)

Поскольку нет такой семантической роли в HTML — файлы и другие компьютерные сущности — можно использовать <mark> для чисто внешнего выделения такого кусочка текста.

[tachisis]

Я прошерстила справочники и случаи употребления бэктиков у нас и думаю вот что:

1. Оставляем бэктики для инлайнового кода: названий тегов, свойств, консольных команд и т.п. Пример: «При этом сами псевдоэлементы используются как два дополнительных стилизуемых элемента внутри ссылки <a>».
2. Для выделений названий файлов, каких-то систем и проч., что не код, но хочется акцентировать — используем италик. Пример: «Наиболее известным JSON-файлом является конфигурационный файл менеджера пакетов NPM — package.json».
3. Отдельно стоящие цифровые значения в тексте не выделяем никак — они и так достаточно выделяются сами по себе, взгляд цепляется за цифру. Соответственно, единицы изменения в этих случаях оформляем по правилам: отбиваем от числа пробелом, допустимо писать латиницей (1 px, 1 см, 1 Гб) либо пишем словами (1 пиксель, 1 сантиметр, 1 гигабайт). Пример: «Если не задать никакое значение font-size, то браузер использует размер по умолчанию. Обычно это 16 px».

Такой порядок оформления наиболее близок к рекомендациям одного из самых авторитетных справочников — «Справочник издателя и автора» Мильчина.

[solarrust]

В целом я согласна, но у меня маленькое сомнение про такую вот ситуацию:
«Задаём свойству margin значение 2px»

По правилу выше значение является числом и должно записываться как «2 px», но мне кажется, что тут оно должно быть заключено в бэктики поскольку является частью кода — значением свойства.

Как следует поступать в таком случае, @tachisis ?

[tachisis]

Если это значение, и это прямо очевидно из текста — это код, бэктики уместны.

[solarrust]

Супер, спасибо за ответ!

[pepelsbey]

Есть это «делаем отступ 2px», то это делаем отступ 2 пикселя или делаем отступ 2 px (пробел от единицы измерения), а если «добавляем свойству margin значение 2px», то добавляем свойству margin значение 2px.

[tachisis]

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