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

• Есть у документации и комментариев в коде одна проблема. Они устаревают. Если не поддерживать документацию и комментарии в актуальном состоянии, они начинают вредить, поскольку мы оказываемся в ситуации, когда код делает одно, а в комментариях написано другое. Если же поддерживать документацию и комментарии в актуальном состоянии, нам приходится делать в два раза больше работы по сравнению с простым написанием кода.
• Ни для кого не секрет, что многие программисты ненавидят писать документацию. Я лично к написанию документации отношусь спокойно, но это еще не значит, что я умею хорошо ее писать. Сколько раз я не пробовал писать документацию, никто кроме меня не был ею доволен. Выходит, для ведения документации либо нужно привлекать отдельных специалистов, либо заставлять программистов делать то, что они не умеют и/или не любят.
• Допустим, мы раскошелились на технических писателей. Является ли хороший технический писатель хорошим программистом? Другими словами, сможет ли он написать толковую документацию, просто глядя на код, или придется посадить рядом с ним кого-то из программистов, чтобы он все объяснил? Сможет ли программист нормально объяснить код, а технический писатель — понять его? Будет ли написанная таким образом документация исчерпывающей и пригодной для чтения программистами?
• Мелкая, казалось бы, проблема — кодировка комментариев. Конечно, если изначально было принято соглашение хранить все исходники в UTF-8, то никакой проблемы нет. Однако мне нередко приходилось сталкиваться с ситуацией, когда часть исходных кодов хранится в кодировке CP1251, часть — в KOI8-R, а часть — в UTF-8. Не всякие средства разработки умеют работать с таким зоопарком кодировок. В общем, кодировки иногда создают проблемы.
• Не совсем очевидная проблема — а где будет хранится документация? Если в почтовом ящике одного из сотрудников, то это 100% плохая идея. Если на wiki-сайте, то это уже лучше. Но его кто-то должен админить — делать бекапы, обновлять ПО, управлять доступом и тп.
• С появлением документации программисты начинают хуже ориентироваться в коде. Что делать, если wiki с документацией лежит, а человек, администрирующий его, недоступен по телефону? Представьте, что программисты, работающие с WinAPI , внезапно остались без доступа к MSDN. Не конец света, конечно, но жить становится намного сложнее. Если у программистов сложилась привычка искать все ответы в уже написанном коде, временная недоступность документации им не страшна.
• Если вы используете систему контроля версий , то в результате автоматического мерджа нескольких веток проекта комментарий может оказаться вовсе не перед тем куском кода, к которому он относится. Или кусок кода может оказаться внутри многострочного комментария.
• Когда программистам не на что полагаться, кроме как на код, это дает им лишний стимул следить за его чистотой.
• С документацией или нет, код все равно приходится читать, и читать его приходится много .

Я ни в коем случае не призываю вас, дескать «не пишите документацию, самодокументирующийся код — наше все». Я только хочу сказать, что в силу описанных выше причин, отсутствие документации вполне имеет право на жизнь. Более того, достоверно известно, что такой подход используется во многих командах. Ведь в действительности вся «документация» уже есть в самом коде, нужно лишь научиться ее находить. Например, с помощью утилиты grep можно легко найти место, где объявляется конкретный класс и изучить его интерфейс. Или найти примеры его использования. Или отыскать все метки типа «TBD» и «FIXME».

Также существует промежуточный вариант между отсутствием документации и документированием всего и вся. Во-первых, вполне достаточно документировать лишь интерфейсы модулей/классов, используя систему типа Doxygen или Javadoc. Во-вторых, использование «очень декларативных» языков, вроде Haskell , снижает потребность в документации. Наконец, в роли документации вполне могут сойти тикеты в багтрекере (особенно в сочетании с VCS). Конечно, при условии, что в тикетах дается нормальная формулировка задачи, а не в стиле «сделать ту фигню, о которой мы сегодня говорили».

А что вы думаете по поводу написанного?

Дополнение: Смиритесь, всем наплевать на стандарты!