Зарегистрируйтесь для доступа к 15+ бесплатным курсам по программированию с тренажером

Оформление кода Как писать классные тексты

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

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

  • Оформление кода должно соответствовать стандартам кодирования, принятым в языке программирования

  • Если вы работаете в формате 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!

Аватары экспертов Хекслета

Остались вопросы? Задайте их в разделе «Обсуждение»

Вам ответят команда поддержки Хекслета или другие студенты

Об обучении на Хекслете

Открыть доступ

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

  • 130 курсов, 2000+ часов теории
  • 1000 практических заданий в браузере
  • 360 000 студентов
Отправляя форму, вы принимаете «Соглашение об обработке персональных данных» и условия «Оферты», а также соглашаетесь с «Условиями использования»

Наши выпускники работают в компаниях:

Логотип компании Альфа Банк
Логотип компании Aviasales
Логотип компании Yandex
Логотип компании Tinkoff

Используйте Хекслет по-максимуму!

  • Задавайте вопросы по уроку
  • Проверяйте знания в квизах
  • Проходите практику прямо в браузере
  • Отслеживайте свой прогресс

Зарегистрируйтесь или войдите в свой аккаунт

Отправляя форму, вы принимаете «Соглашение об обработке персональных данных» и условия «Оферты», а также соглашаетесь с «Условиями использования»
Изображение Тото

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