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

Типичные причины, приводимые разработчиками, включают:

Мои навыки письма плохие.

Я ненавижу писать.

Документацию никто не читает.

У меня нет времени писать это.

Это не моя работа.

Написание кода важнее, чем написание документов.

Так как многие люди не любят писать документацию, я задаюсь вопросом: действительно ли необходимо ее писать?

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

Таким образом, наличие документации, объясняющей, что делает код, должно снизить стоимость обслуживания программного обеспечения.

Как писал Том Демарко в статье «Почему программное обеспечение стоит так дорого?» (Dorset House, 1995):

«Есть два знакомых варианта проблемы с документацией: а) вы пишете всю внутреннюю документацию, которая, как вы знаете, вам нужна, и платите за это ужасную цену, или б) вы не пишете всю внутреннюю документацию, которая вам нужна, и вы платите ужасная цена за это».

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

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

Один из принципов Agile Manifesto гласит:

«Рабочее программное обеспечение важнее исчерпывающей документации»

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

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

Идея иметь красноречивый код, несомненно, увлекательна. Это позволило бы разработчику сосредоточиться на разработке программного обеспечения, что, безусловно, является более привычной задачей, и позволило бы избежать затрат на создание дополнительного артефакта для обслуживания в течение долгого времени.

Но в повседневной жизни действительно ли код, созданный большинством программистов, понятен, чтобы быть надлежащей документацией? Действительно ли достижима мечта о самодокументирующемся коде? Можем ли мы найти реальный компромисс между кодом и производством документации?

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

Пожалуйста, оставьте комментарий.