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

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

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

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

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

Модульные тесты представляют собой документы, описывающие самый нижний архитектурный уровень системы. Они однозначны, точны, написаны на языке, понятном для аудитории, и достаточно точны и формальны для выполнения. Это самая лучшая низкоуровневая документация, которая только возможна. Какой профессионал не захочет создать такую документацию?