Вклад в проект Zstandard

Мы стремимся сделать процесс внесения вклада в этот проект максимально простым и прозрачным.

Наш процесс разработки

Новые версии создаются в ветке "dev", либо в отдельной функциональной ветке. Когда они считаются готовыми для выпуска, они сливаются в ветку "release".

Как следствие, все вклады должны проходить через ветку "dev" или их собственную функциональную ветку.

Пулл-запросы

Мы активно приветствуем ваши пулл-запросы.

1. Создайте форк репозитория и создайте свою ветку с dev.
2. Если вы добавили код, который следует тестировать, добавьте тесты.
3. Если вы изменили API, обновите документацию.
4. Убедитесь, что набор тестов успешно завершается.
5. Убедитесь, что ваш код проходит проверку на соответствие стандартам.
6. Если вы еще этого не сделали, заполните Договор о лицензии на вклад ("CLA").

Договор о лицензии на вклад ("CLA")

Чтобы принять ваш пулл-запрос, нам требуется, чтобы вы представили Договор о лицензии на вклад ("CLA"). Вам потребуется это сделать всего один раз для работы над любыми открытыми проектами компании Facebook.

Заполните ваш "CLA" здесь: https://code.facebook.com/cla

Процесс работы

Проект Zstd использует ветвной подход для изменения кодовой базы. Обычно Zstd будет использовать новую ветку для каждого значительного темы. Для небольших изменений можно объединять несколько связанных изменений в одну ветку.

Наши процессы вклада работают в трех основных этапах:

1. Локальное развитие
   • Обновление:
     • Выполните проверку своего форка Zstd, если вы ещё этого не сделали

     git checkout https://github.com/<username>/zstd
     cd zstd
     • Обновите локальную ветку развития

     git pull https://github.com/facebook/zstd dev
     git push origin dev
     • Тема и развитие:
       • Создайте новую ветку на своем форке относительно темы, которую вы развиваете

       # Имена веток должны быть краткими, но достаточно информативными
       git checkout -b <branch-name>
       git push origin <branch-name>
       • Создайте коммиты и отправьте

       # выполните некоторые изменения =
       git add -u && git commit -m <сообщение>
       git push origin <branch-name>
       • Примечание: выполните локальные тесты, чтобы убедиться, что ваши изменения не сломали существующие функции
         • Быстрый контроль

         make check
         • Долгий контроль

         make test
2. Отзыв кода и тесты CI
   • Убедитесь, что тесты CI проходят:
     • Перед тем как делиться чем-либо с сообществом, создайте пулл-запрос в своем форке против ветки dev и убедитесь, что все тесты CI GitHub Actions прошли. Подробнее см. раздел ниже о непрерывной интеграции.
     • Убедитесь, что статический анализ проходит на вашей машине. Подробнее см. раздел ниже о статическом анализе.
   • Создайте пулл-запрос:
     • Когда вы готовы поделиться своими изменениями с сообществом, создайте пулл-запрос из своей ветки к facebook:dev. Это можно легко сделать, нажав кнопку 'Создать пулл-запрос' на домашней странице вашего форка.
     • Оттуда выберите ветку, где вы выполнили изменения, как исходную ветку и facebook:dev как целевую.
     • Исследуйте представленное различие между двумя ветками, чтобы убедиться, что там нет чего-то неожиданного.
   • Напишите хорошее описание пулл-запроса:
     • Хотя наши вкладчики не следуют строго установленному шаблону, мы хотели бы, чтобы они достаточно подробно суммировали и мотивировали предлагаемые изменения. Мы рекомендуем всем пулл-запросам хотя бы косвенно затрагивать следующие пункты.
       • Является ли этот пулл-запрос важным и почему?
       • Адресует ли он проблему? Если да, то какую? (предоставьте ссылки для удобства, пожалуйста)
       • Является ли это новой функцией? Если да, то зачем она полезна и/или необходима?
       • Есть ли какие-либо фоновые ссылки и документы, которые рецензенты должны знать для правильной оценки этих изменений?
     • Примечание: укажите любые дизайнерские и архитектурные решения, которые вы приняли, и причины их выбора.
     • Примечание: если вы работали вместе с конкретным пользователем и хотите, чтобы он проверил вашу работу, обязательно укажите его имя используя (@)
   • Предложите пулл-запрос и итерируйтесь с обратной связью.
3. Слияние и выпуск
   • Получение одобрения:
     • Вам придется итерировать свои изменения с обратной связью других участников до момента, когда ваш пулл-запрос может быть безопасно слит.
     • Чтобы избежать слишком много замечаний по стилю и конвенциям, убедитесь, что вы просмотрели наш раздел о стиле перед созданием пулл-запроса.
     • В конце концов, кто-то из команды Zstd одобрит ваш пулл-запрос, и вскоре после этого сложит его в ветку dev.
   • Поддержка:
     • Большинство PR связаны с одной или несколькycastle/largeNbDicts` и ничего другого, вы можете выполнить:

scan-build make -C contrib/largeNbDicts largeNbDicts

Питфоллы статического анализа

scan-build является частью нашей регулярной системы CI. Другие статические анализаторы не используются постоянно.

Иногда полезно смотреть на дополнительные статические анализаторы, но множить количество анализаторов, выполняемых при каждом коммите и пулл-запросе, не лучшая идея. Причины:- Статические анализаторы часто содержат большое количество ложноположительных сигналов. Соотношение сигналов к шуму довольно низкое.

• Хорошая политика CI — "ноля терпимости к предупреждениям". То есть все проблемы должны быть решены, включая ложноположительные. Это быстро становится трудоёмкой задачей.
• Множество статических анализаторов имеют различные виды ложноположительных сигналов, иногда применимых к одному и тому же коду, но по-разному, что приводит к:
  • запутанному коду, пытающемуся удовлетворить множество ограничений, что снижает читаемость и, следовательно, поддержку.
  • иногда эти ограничения взаимоисключающие: если одна проблема решена, другой статический анализатор начнёт жаловаться, они не могут быть довольны одновременно.
• Как будто этого было недостаточно, список ложноположительных сигналов меняется с каждым обновлением. Следование одному статическому анализатору уже сложно, а множество с их собственным графиком обновлений — это скорее препятствие, чем помощь.

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

Непрерывная интеграция

Тесты CI выполняются каждый раз, когда создаётся или обновляется пулл-запрос. Конкретные тесты, которые выполняются, зависят от целевой ветки, которую вы указываете. Некоторые тесты занимают больше времени, чем другие. В настоящее время наша система CI настроена на выполнение короткой серии тестов при создании пулл-запроса к ветке dev и длинной серии тестов при создании пулл-запроса к ветке release. Вы можете найти информацию о том, что выполняется, в конфигурационных файлах соответствующего сервиса CI.

Большинство людей просто хотят создать пулл-запрос с целевой веткой, равной их локальной ветке dev Zstd. Вы можете затем найти статус тестов на странице пулл-запроса. Также вы можете повторно запустить тесты и отменить запущенные тесты с помощью страницы пулл-запроса или панели управления соответствующего сервиса CI.

практически все CI Zstd выполняются на GitHub Actions (��置在.github/workflows目录下)，这些操作会在您自己的分叉中创建拉取请求时自动运行。少数测试则在其他服务上运行（例如，Travis CI、Circle CI、AppVeyor）。这些需要在您的本地分支上进行设置，并且至少对于Travis CI来说会带来成本。因此，如果您的本地分支上的拉取请求通过了GitHub Actions，请随时提交针对主仓库的拉取请求。

第三方CI

一小部分测试无法在GitHub Actions上执行或尚未迁移。为此情况我们使用不同的第三方服务（见下方表格）。为Zstd贡献而设置这些服务的需求并不强制；然而，我们提供了链接到那些希望获得早期信号的人的说明。

注：上述提供的指南主要涵盖了从零开始配置带有CI的存储库的过程。 对于将CI配置到您自己fork中的Zstd的主要思想应该是相同的，但是您可能需要遵循略有不同的步骤。特别是，请忽略任何与配置文件设置相关的指示（因为Zstd已经在每种服务中都有相应的配置）。

高性能

高性能对zstd至关重要，我们只接受那些性能特征和相关折衷经过充分分析、重现并展示的pull请求。这种高标准的要求意味着每个潜在影响性能的pull请求都需要花费大量时间来正确验证。尽管如此，我们总是欢迎旨在提高性能（或降低性能以换取其他优势）的贡献。请在发送与性能相关的pull请求之前注意以下几点：

1. 虽然zstd不像gzip那样古老，但它已存在了一段时间，并且其演变过程已在过去的Github问题和pull请求中有很好的记录。也许你特定的性能优化方法以前已经被考虑过。请花一点时间搜索旧的问题和pull请求，使用与你的未来pull请求相关的关键词。当然，某个主题以前已被讨论过（并且可能因某种原因被拒绝），这并不意味着它不值得再次审查。但在这种情况下，了解该主题的历史背景将有助于你在做出贡献前更好地理解。
2. 在微基准测试小增益或损失时，噪声与真实性能改进之间的差异可能会非常微妙。唯一的方法就是进行全面的基准测试。如果你能在发送pull请求之前完成长时间多平台的基准测试，那对我们来说将是极大的帮助。当然，你不可能对你所做的更改在每一个处理器和操作系统上都进行基准测试，但请尽你所能吧:)
3. 对于特定的操作系统、处理器制造商、编译器或网络系统的性能优化是一种完全合理的做法，只要它不会降低zstd的整体性能。这是一个难以平衡的任务，但在发送特定于clang、Windows等的更改时，请记住zstd的其他方面。## Бенчмаркирование производительности Микробенчмаркинг производительности — это сложная задача, но также необходимая для zstd. Мы ценим эмпирические тесты больше, чем теоретические спекуляции. Этот гайд не идеален, но для большинства случаев это хорошее место для начала.

Устойчивость

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

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

1. Самый простой способ значительно повысить устойчивость ваших бенчмарков — это запуск их несколько раз и последующее объединение результатов этих запусков. Как правило, чем меньше изменения вы пытаетесь измерить, тем больше образцов запусков бенчмарков вам потребуется для получения надежных результатов. Вот некоторые дополнительные моменты, которые следует учесть при проведении нескольких пробных запусков:
   • То, как вы объединяете свои образцы, важно. Вы можете быть склонны использовать среднее значение ваших результатов. Хотя это определенно будет более устойчивым числом, чем один образец бенчмарка, вы можете получить лучшие результаты, взяв медиану. Среднее значение не устойчиво к выбросам, тогда как медиана — да. Лучше всего, вы можете просто взять самый быстрый временной интервал вашего бенчмарка для каждого запуска, так как это вероятно самый быстрый временной интервал, на котором ваш процесс сможет работать. По нашему опыту, этот метод (объединение путем выбора самого быстрого временного интервала) является наиболее устойчивым подходом.
   • Чем больше образцов у вас есть, тем более устойчивыми должны быть ваши бенчмарки. Вы можете проверить вашу улучшенную устойчивость, просмотрев размер ваших доверительных интервалов по мере увеличения колич�数量超过限制，以下是剩余部分的翻译：

数量 |---------|

• Большинство процессоров потребуют некоторое время, чтобы «разогреться» при выполнении чего-либо. Обсервации, которые вы собираете во время этого периода, будут сильно отличаться от истинного значения производительности. Очень большое количество образцов поможет частично решить эту проблему, но вы также можете прямо её адресовать, просто не включая первые n итераций вашего бенчмарка в ваши объединения. Вы можете определить n, просто просматривая результаты каждой итерации и затем рукотворно выбирая хороший порог после которого вариация результатов кажется стабилизирующейся。

2. Вы не сможете получить надёжные бенчмарки, если ваша основная машина одновременно выполняет другое CPU/памяти-интенсивное приложение в фоновом режиме. Например, если вы выполняете бенчмарки на своем личном ноутбуке, вы должны закрыть все приложения (включая ваш редактор кода и браузер) перед запуском бенчмарков. У вас могут быть невидимые фоновые приложения. Вы можете узнать, какие это, просмотрев либо Activity Monitor на Mac, либо Task Manager на Windows. Вы получите более устойчивые результаты бенчмарков, если завершите эти процессы тоже。
   • Если у вас несколько ядер, вы можете запустить свой бенчмарк на зарезервированном ядре, чтобы предотвратить загрязнение со стороны других ОС и пользовательских процессов. Есть множество способов сделать это в зависимости от вашей ОС：
     • На Linux машинах, вы можете использовать https://github.com/lpechacek/cpuset。
     • На Windows, вы можете "Установить Процессор Аффинитет" с помощью https://www.thewindowsclub.com/processor-affinity-windows
     • На Mac, вы можете попробовать использовать их специализированный API аффинитета https://developer.apple.com/library/archive/releasenotes/Performance/RN-AffinityAPI/#//apple_ref/doc/uid/TP40006635-CH1-DontLinkElementID_2
3. Для бенчмаркинга вы, скорее всего, закончите созданием отдельной программы C/C++, которая будет связывать libzstd. Динамическая связывание вашей библиотеки введёт некоторую добавленную вариацию (не слишком много, но определённо некоторую). Статическое связывание libzstd будет более устойчивым. Статические библиотеки должны быть активированы по умолчанию при сборке zstd。
4. Используйте профайлер с хорошим высокочастотным таймером. Подробности об этом даны ниже в разделе о профайлерах。
5. Отключите масштабирование частоты, турбо-ускорение и случайное расположение адресного пространства (это будет зависеть от ОС)。
6. Избегайте использования хранилища. На некоторых системах вы можете использовать tmpfs。Расположение программы, входных данных и выходных данных на tmpfs позволяет избежать обращения к реальной системе хранения, что может существенно влиять на производительность。

Также обратитесь к руководству LLVM по бенчмаркингу здесь：https://llvm.org/docs/Benchmarking.html

Бенчмаркирование zstd

Наиболее быстрым сигналом о ваших изменениях производительности является встроенный zstd cli опция bench。Вы можете запустить Zstd так, как обычно делали бы для вашего случая, используя определённый набор опций, а затем дополнительно указать опцию -b#。Выполнение этого запустит нашу конвейерную линию бенчмарков для предоставленных вами опций。Если вы хотите посмотреть внутреннюю работу этого бенчмаркового скрипта, вы можете проверить programs/benchzstd.c

Например：предположим, вы внесли изменения, которые считаете улучшающими скорость zstd уровня 1。Первым шагом должно быть использование zstd -b，чтобы оценить, действительно ли произошло какое-либо улучшение。Вы можете попробовать что-то вроде этого。Примечание：вы можете использовать опцию -i для указания времени выполнения вашего бенчмарка в секундах（по умолчанию 3 секунды）。Обычно, чем длиннее время выполнения, тем более устойчивыми будут ваши результаты。

$ git checkout <commit-before-your-change>
$ make && cp zstd zstd-old
$ git checkout <commit-after-your-change>
$ make && cp zstd zstd-new
$ zstd-old -i5 -b1 <your-test-data>
 1<your-test-data>         :      8990 ->      3992 (2.252), 302.6 MB/s , 626.4 MB/s
$ zstd-new -i5 -b1 <your-test-data>
 1<your-test-data>         :      8990 ->      3992 (2.252), 302.8 MB/s , 628.4 MB/s
```Если ваш выигрыш производительности достаточно велик, чтобы быть заметным вопреки естественному шуму на вашем компьютере, то использование benchzstd одного будет недостаточно для подтверждения влияния ваших изменений. Например, результаты выше показывают, что фактически ничего не изменилось, но могло быть небольшое (<3%) улучшение, которое было затушевано шумом на машине. Так что, если вы не видите значительного улучшения производительности (10-15% постоянно) одним таким методом оценки, это будет недостаточно.


### Профилирование
Существует множество отличных профиллеров. Мы кратко упомянем, как вы можете профилировать свой код с использованием `instruments` на Mac, `perf` на Linux и `Visual Studio Profiler` на Windows.

Предположим, у вас есть идея для изменения, которое вы считаете может предоставить хорошие улучшения производительности для сжатия уровня 1 в zstd. Обычно это значит, что вы определили участок кода, который вы считаете можно сделать более эффективным.

Первым шагом будет убедиться, что данный участок кода действительно занимает значительное время для выполнения. Обычно нет смысла оптимизировать что-то, что составляет менее 0.0001% от общего времени выполнения. К счастью, есть инструменты, которые помогают с этим. Профиллеры позволят вам увидеть, сколько времени ваш код тратит внутри определенной функции. Если ваш целевой кодовый фрагмент является частью функции, может быть полезно попытаться изолировать этот фрагмент, переместив его в свою собственную функцию (обычно это не обязательно, но может быть полезным).

Большинство профиллеров (включая профиллеры, обсуждаемые ниже) сгенерируют для вас граф вызова функций. Ваша цель будет найти интересующую вас функцию в этом графе и затем исследовать время, затраченное внутри неё. Также может быть полезно посмотреть на аннотированный ассемблер, который большинство профиллеров предоставляют.

#### Инструменты
Мы снова рассмотрим ситуацию, где вы считаете, что определили участок кода, производительность которого можно улучшить. Следуйте этим шагам для профилирования вашего кода с использованием инструментов:

1. Откройте инструменты
2. Выберите `Time Profiler` из списка стандартных шаблонов
3. Закройте все остальные приложения, кроме окна с вашими инструментами и терминала
4. Запустите свой скрипт тестирования производительности из терминального окна
   * Вам потребуется тест, который будет работать как минимум несколько секунд (5 секунд обычно достаточно). Это позволит профилировщику получить данные для анализа и вам будет достаточно времени, чтобы присоединиться к процессу тестирования.
   * Я буду использовать benchzstd в качестве своего скрипта тестирования производительности в этом примере:

$ zstd -b1 -i5 <мои-данные> # это будет выполняться 5 секунд

5. После запуска вашего скрипта тестирования производительности вернитесь обратно к инструментам и присоедините процесс к Time Profiler. Для этого выполните следующие действия:
* Нажмите на выпадающий список `Все процессы` в левом верхнем углу панели инструментов.
* Выберите ваш процесс из выпадающего списка. В моем случае, он будет просто помечен как `zstd`
* Нажмите ярко-красную кнопку записи в левом верхнем углу панели инструментов
6. Ваш профилировщик теперь начнет собирать метрики от вашего скрипта тестирования производительности. Как только вы считаете, что собрали достаточное количество образцов (обычно это происходит после 3 секунд записи), остановите профилировщик.
7. Убедитесь, что в нижней части экрана выбран пункт `профиль`.
8. Вы должны видеть свою диаграмму вызовов.
* Если вы не видите диаграмму вызовов или незавершенную диаграмму вызовов, убедитесь, что вы скомпилировали zstd и ваш скрипт тестирования производительности с использованием флагов отладки. На Mac и Linux это означает, что вам придется предоставить флаг `-g` вместе со своим скриптом сборки. Возможно, вам также придется предоставить флаг `-fno-omit-frame-pointer`.

#### Perf

Этот вики имеет довольно подробное руководство по началу работы с perf, поэтому мы оставляем вас самостоятельно изучать его, если вы начинаете работу:

https://perf.wiki.kernel.org/index.php/Tutorial

Некоторые общие замечания по поводу perf:
* Используйте `perf stat -r # <bench-program>` для быстрого получения некоторых значимых временных и счетчиковых статистик. Perf использует высокоточный таймер, и это, скорее всего, одно из первых вещей, которые ваша команда будет выполнять при оценке вашего запроса.
* Perf имеет длинный список аппаратных счетчиков, которые можно просмотреть с помощью `perf --list`. Когда вы измеряете оптимизации, стоит попробовать убедиться, что те аппаратные счетчики, которые вы ожидаете будут затронуты изменениями, действительно таковыми являются. Например, если вы ожидаете, что число пропущенных запросов к кешу L1 уменьшится благодаря вашим изменениям, вы можете посмотреть на счетчик `L1-dcache-load-misses`
* Аппаратные счетчики perf не будут работать на виртуальной машине.

#### Visual Studio

TODO

## Проблемы
Мы используем GitHub проблемы для отслеживания открытых багов. Пожалуйста, убедитесь, что ваше описание четкое и содержит достаточно инструкций для воспроизведения проблемы.

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

## Стиль программирования
Это довольно широкий вопрос, который трудно свести к одному абзацу. По правилу большинства, попытайтесь имитировать стиль программирования аналогичных строк кода рядом с вашим вкладом.
Следующий список правил, применяемых в базе кода zstd, является неполным:

### C90
Эта база кода следует строгому стандарту C90,
с двумя расширениями: типами `long long` 64-битного размера и макросами с переменным количеством аргументов.
Это правило применяется строго к коду внутри `lib/` и `programs/`.
Подпроекты в `contrib/` могут использовать другие соглашения.

### Прямая совместимость C++: манипуляция символов
Все публичные объявления символов должны быть заключены в `extern "C" { ... }`,
чтобы этот проект мог компилироваться как C++98 код,
и связываться с C++ приложениями.### Минимальная экономия
Это требование дизайна важно для сохранения портативности кодовой базы.
#### Зависимости
- Уменьшите зависимости до минимального уровня возможного.
Любая зависимость должна рассматриваться как «плохая» по умолчанию,
и допускаться только потому, что она обеспечивает услугу лучше, чем может быть достигнуто локально.
Единственные внешние зависимости, которые эта репозитория допускает, — это стандартные библиотеки C и системные заголовочные файлы уровнем ниже.
- Внутри `lib/`, данная политика еще более жесткая.
Единственными допустимыми внешними зависимостями являются `<assert.h>`, `<stdlib.h>`, `<string.h>`,
но даже они не используются напрямую.
В частности, никакая функция не должна никогда выделять память на куче напрямую,
и вместо этого должна использовать `ZSTD_malloc()` и эквивалентные функции.
Другие допустимые заголовочные файлы без символов — это `<stddef.h>` и `<limits.h>`.
- В рамках проекта существует строгая иерархия зависимостей, которая должна соблюдаться.
`programs/` может зависеть от `lib/`, но только от его публичного API.
Внутри `lib/`, `lib/common` не зависит ни от одного другого каталога.
`lib/compress` и `lib/decompress` не должны зависеть друг от друга.
`lib/dictBuilder` может зависеть от `lib/common` и `lib/compress`, но не от `lib/decompress`.
#### Ресурсы
- Функции в `lib/` должны использовать очень мало места стека,
максимум нескольких десятков байтов.
Все больше должно использовать аллокатор кучи,
либо требовать рукотворное использование буферов.


### Названия
* Все публичные символы имеют префикс `ZSTD_`
+ Частные символы, область видимости которых ограничивается их собственным модулем, освобождены от данного требования.
 Однако, поскольку исходный код `libzstd` может быть объединен,
 каждое имя символа должно стремиться быть уникальным и оставаться таким.
 Избегайте слишком общих названий, которые могут стать причиной будущего конфликта.
 Обычно это означает использование некоторой формы префикса.
* Для символов (функций и переменных), конвенция названия — `PREFIX_camelCase`.
+ В некоторых продвинутых случаях, можно найти:
 - `PREFIX_prefix2_camelCase`
 - `PREFIX_camelCase_extendedQualifier`
* Многоразрядные названия обычно состоят из действия, последующего объекта:
- Например: `ZSTD_createCCtx()`
* Предпочитайте положительные действия
- `goBackward` вместо `notGoForward`
* Названия типов (`struct`, и т.д.) следуют похожей конвенции,
за исключением того, что они разрешены и даже приглашаются начинаться с заглавной буквы.
Пример: `ZSTD_CCtx`, `ZSTD_CDict`
* Макросы имеют все заглавные буквы.
Те же правила составления (`PREFIX_NAME_QUALIFIER`) применимы.
* Имена файлов состоят из всех строчных букв.
Конвенция — `snake_case`.
Имена файлов **должны** быть уникальными во всей кодовой базе,
даже когда они находятся в явно разделенных директориях.

### Квалификаторы
* Эта база кода дружелюбна к `const`, если не сказать фанатично.
Любая переменная, которую можно сделать `const` (то есть, только для чтения), **должна** быть `const`.
Любой указатель, содержимое которого не будет изменено, должен быть `const`.
Эта характеристика контролируется на уровне компилятора.
`const` переменные являются важным сигналом для читающих, что эта переменная не изменяется.
Соответственно, неконстантные переменные являются сигналом для читающих быть внимательными к возможным изменениям позднее в функции.
* Если функция должна быть встроенной, укажите это явно,
используя собственные переносимые макросы проекта, такие как `FORCE_INLINE_ATTR`,
определенные в `lib/common/compiler.h`.

### Отладка
* **Ассертации** приветствуются, и должны использоваться максимально широко,
чтобы контролировать любое условие, которое код ожидает для корректного выполнения.
Эти проверки ассертаций будут выполняться в режиме отладки и отключены в рабочем режиме.
* Для трассировки, данный проект предоставляет свои собственные макросы отладки,
в частности `DEBUGLOG(уровень, ...)`, определенные в `lib/common/debug.h`.

### Документация кода
* Избегайте документации кода, которая просто повторяет то, что уже заявлено в коде.
Вместо этого, когда применимо, предпочитайте использование кода как основного способа передачи объяснений.
Пример 1: `int nbTokens = n;` вместо `int i = n; /* i is a nb of tokens *./`.
Пример 2: `assert(size > 0);` вместо `/* здесь, size должен быть положительным */`.
* На уровне декларации, документация объясняет, как использовать функцию или переменную,
и когда применимо, почему она нужна, какие сценарии могут быть полезны.
* На уровне реализации, документация объясняет общую структуру алгоритма,
и когда применимо, почему был сделан именно такой выбор.

### Общая структура
* 4 пробела для отступов вместо табуляции
* Документация кода должна немедленно предшествовать объявлению функции или её реализации
* Реализация функции и её документация должны быть отделены пустыми строками