В этом уроке мы поговорим о финальном шаге работы над текстом — правильном оформлении фрагментов кода. Здесь вы узнаете, какие стандарты оформления приняты на Хекслете.
Сначала обсудим общие правила оформления:
-
Оформление кода должно соответствовать стандартам кодирования, принятым в языке программирования
-
Если вы работаете в формате Markdown, обязательно настройте линтер и превью готового документа в своем редакторе кода. Для единого стиля мы рекомендуем линтер markdownlint
-
Обратные одинарные кавычки (бэктики) используем только для кода:
const a = 5; -
В тексте урока определения и важные понятия выделяем болдом:
"Чтобы не копировать выражение, достаточно создать с ним переменную" -
Для обозначения комбинации клавиш можно использовать парный тег:
<kbd>Ctrl+P</kbd>для Markdown
Фрагменты кода
Примеры кода отбиваются пустыми строками:
В первом уроке мы напишем программу `Hello, World!`. Чтобы сделать это, нужно дать компьютеру специальную команду. В языке Python это — `print()`:
```python
print('Hello, World!')
# => Hello, World!
```
Чтобы объяснить подробнее, какое значение выводится на экран, мы использовали комментарий.Функции
Для описания функций следует опираться на следующие правила:
Правило 1. Если функция экспортируется по умолчанию, то имя функции опускается:
Экспортируйте по умолчанию функцию, которая...Правило 2. Имя функции обрамляется бэктиками и указывается со скобками вызова, даже если аргументы отсутствуют:
Экспортируйте функцию `f()`, которая...Правило 3. Во фрагментах кода вызов функции, экспортированной по умолчанию, указывается с импортом:
import f from 'solution';
f(''); // trueИмена файлов
В тексте упражнения имена файлов форматируются курсивом:
Смотрите файл *example.json* в этом упражненииТаким же образом оформляются пути файловой системы и названия библиотек:
Например: библиотека *Jest* запускает файлы из каталога *__tests__*Импорты
При первом использовании кода, определенного в других неймспейсах, модулях, пакетах, нужно показывать его импорт.
import fs from 'fs';
const result = fs.readFileSync('/etc/passwd');Далее выводим импорт по необходимости.
Команды
Для демонстрации команд и их вывода используют тройные бектики с языком ```bash. В примерах команд нет дополнительных символов $ или #. Пример оформления:
```bash
make start
make compose
echo 'Hello, World!'
```Результат
Для демонстрации результата выражения используются две конструкции:
-
Просто комментарий
-
Комментарий со стрелкой
⇒
Вывод демонстрируется как есть (без дополнительных кавычек). Стрелка добавляется там, где результат выводится на экран:
const result = Math.sqrt(16); // 4
console.log(result); // => 4
console.log('hello, world!') // => hello, world!Если комментарий не помещается в одну строку, то лучше перенести его ниже:
print('I am the King')
# For Lannisters! For Winterfell!
Остались вопросы? Задайте их в разделе «Обсуждение»
Вам ответят команда поддержки Хекслета или другие студенты
