Теория: Оформление кода

В этом уроке мы поговорим о финальном шаге работы над текстом — правильном оформлении фрагментов кода. Здесь вы узнаете, какие стандарты оформления приняты на Хекслете.

Сначала обсудим общие правила оформления:

• Оформление кода должно соответствовать стандартам кодирования, принятым в языке программирования
• Если вы работаете в формате 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* запускает файлы из каталога *__t​ests__*

Импорты

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

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!