Документированность кода.

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

• Кому нужна документация?
• Кто должен ее писать?
• Что должно в ней быть написано?
• Насколько документация должна быть полной?
• Когда документацией можно пренебречь, ускорив тем самым разработку?

А так же несколько технических вопросов:

• Что можно использовать для написания документации?
• Где хранить документацию?
• Какое программное обеспечение в этом может помочь?

Итак, первый вопрос "Кому нужна документация?"

Документация нужна всем людям, которые буду работать с продуктом, который вы разрабатываете. В особенности разработчикам, но без документации, проект, скорее всего, будет медленнее развиваться, что скажется на отношении пользователя к продукту. А самое главное, она нужна ВАМ. Очень простая и часто используемая ситуация. Вы разрабатываете программу. Написали первую версию, забыли. Через полгода вы решаете расширить ее функционал. Вы открываете исходники программы, и если в них нету комментариев(это главный вид документации к коду) вы заново начинаете понимать все программу только по коду. Во время этого процесса не редко возникает мысль написать все заново, что бы не копаться в этом коде, который стал не понятен.

Далее по списку "Кто должен ее писать?"

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

"Что должно в ней быть написано?"

Здесь есть разница в "уровне" документации. Если это комментарии внутри кода, то они должны четка описывать то, что прокомментировано, без лишних фраз на подобии "ну а тут я решил сделать так... мне в голову перед сном пришло...", полностью и по делу. Если это документация вне кода, а например API Reference вашей системы, то здесь важно описать все, так же по делу и без лишней отсебятины . А так же можно привести примеры, особенно в трудно понимаемых местах.

"Насколько документация должна быть полной?"

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

"Когда документацией можно пренебречь, ускорив тем самым разработку?"

Никогда! Единственное исключение это одноразовая утилита или скрипт в 20-50 строк. И то, для второго случая лучше описать что он делает, что бы не забыть.

А теперь не много технических вопросов. Хотя в них я и сам далеко не эксперт, и буду рад любым дополнениям к моим ответам.

"Что можно использовать для написания документации?"

Я не знаю специальных инструментов документирования. Но в некоторых языках такие инструменты уже имеются. Например у Java есть Javadoc, у Python есть PyDoc. Я работал только с Javadoc и могу сказать что это достаточно удобно. Документация пишется прямо в коде, это специально выделенные комментарии, а в любое время вы можете создать HTML справку по вашему коду. Это особенно удобно для создания библиотек, так как упрощает написание справки к ним. С другими же работать не приходилось.

"Где хранить документацию?"

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

"Какое программное обеспечение в этом может помочь?"
А вот с этим вопрос я обращаюсь к вам, так как сам не знаю специальных инструментов для этого, кроме как функции генерации справки в разных IDE.


На этом все. Оставляете свои вопросы, замечания и просто комментарии. Если вам понравился такой вид статей(несколько учебно-познавательный), то пишите об этом в комментариях и очень даже возможно что я напишу еще интересные статьи в данном стиле. Всем удачи, до скорых встреч.