Прежде чем изучать, как документировать код, давайте сначала рассмотрим некоторые исследования, которые были проведены по передовым методам документирования кода, так как это может определить наше направление и подход.
Несколько академических статей выделяются как заслуживающие внимания:
- Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++
В этой статье рассказывается, как разработчики из Google находят и используют документацию кода. Исследователи обнаружили, что простой код иногда разработчики предпочитают исследовать напрямую. Однако для более сложного кода разработчики обращаются к документации кода, часто просматривая формальные объявления классов для получения нужной информации. В других случаях они смотрят на комментарии в коде реализации. Помимо предоставления руководства по наилучшему расположению документации, исследователи также определяют, какой тип ответов и рекомендации разработчики хотят получить в документации.
- Как разработчики используют документацию API: изучение наблюдений
В этой статье исследователи смотрели на то, как разработчики взаимодействуют с документацией API, и обнаружили сочетание как систематического (сначала читайте, изучайте позже), так и оппортунистического (изучайте сначала, читайте позже) стилей обучения. Хотя мы часто пишем систематически, сосредоточение внимания на оппортунистическом поведении может быть более полезным, что побудит нас более внимательно следить за улучшением поиска, навигации, интерактивных компонентов, устранения неполадок, сообщений об ошибках и других функций, ориентированных на действия.
Обе эти статьи взяты из научных журналов. На самом деле редко можно найти исследования о документации API в академических журналах (не знаю почему), и когда вы их находите, они часто бывают в инженерных журналах, или журналах по информатике (а не в журналах по техническим коммуникациям).
Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++
- Тип кода, которому нужна документация
- Когда документировать код
- Вопросы, решаемые в документации кода
- Заключение
Как разработчики используют документацию API: изучение наблюдений