Документация

Документация к коду

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

Документация модуля описывает всю логику в файле в целом, не зависимо от того какую задачу функционал в этом файле решает. Если в файле один класс, который сохраняет пользовательские настройки отображения иконок в меню и в документации написано что-то вроде «Provide implementation for user menu's icons settings», вполне вероятно, что через какое-то время придется переписывать на «Provide implementation for user interface settings», потому что в этот же файл решили добавить обработчик настроек ленты новостей.

Документация класса описывает ответственность объекта, который будет использоваться в коде программы.

Разделяйте документацию функции на секции:

• итоговая строка — не больше одного предложения, что действительно делает ваш код. Если строка описывает два действия или по длине больше, чем положено (например, больше 119 символов в языке Python), значит, у функции много ответственности;
• детальное описание процессов в вашем коде, если он усложнен логикой;
• аргументы, которые она принимает. Указывайте какие типы данных вы ожидаете и приводите примеры;
• тип данных, которые она возвращает;
• ссылки на ресурсы, которые будут полезны другим программистам, читающим ваш код. Интегрируете API — укажите ссылки на его документацию.

Документация к проекту

Документация проекта должна содержать:

• актуальность проекта, например, датированный список релизов и изменений с описанием изменений;
• описание проекта и какие задачи он решает;
• как установить и начать использовать;
• примеры, подсказки и неочевидные вещи;
• типичные проблемы и F.A.Q.;
• куда можно обратиться за помощью, если решение проблемы не удалось найти;
• раздел для разработчиков — как скачать проект, вносить и присылать изменения.