Общепризнанно(?), что внутренние документирование (комментарии в коде, техническая документация - описания классов, идеологические и архитектурные документы) чрезвычайно желательно. Открытым остается вопрос: в каком объеме это документирование должно делаться. Потому что, если документация очень подробна, отдельной проблемой (решение которой требует больших(!) трудозатрат) становится написания документации и (особенно) поддержка ее актуальности.
В каком объеме документриуются ваши проекты? Используете ли вы какие-нибудь стандартные средства документирования (типа Doc-o-matic, javadoc)? А может быть, в вашей компании пришли к выводу, что внутренние документы все равно никто не читает и поэтому не стали тратить на них время?
[Ответ]
Самый легкий способ документирвания - комментарии в коде. Однако в этом случае приходится постоянно обращатья к коду при необходимрости получить информацию, кроме того нужый комментарий в коде нужно еще найти. Да и ссылки на другие комментарии не разместишь.
Поэтому очень желательно иметь внешнюю документацию - в отдельных файлах типа файлов справки или в формате html. Но тут же возникает проблема поддержания актуальности документации. В случае, если документация строится на основе комментариев специальной программой документатором, документация актуальна. В случае же, когда документация синхронизируется вручную, как показывает опыт, документация всегда неактуальна. А при большом объеме поддержание актуальности становится отдельной проблемой.
Оборотной стороной использования документаторов является то, что возникает соблазн сделать документацию как можно более подробной - тем самым код засоряется большими комментариями и становится трудночитаемым. Модуль на 500 строк кода может иметь 500 строк комментариев. Да и в идеале, кроме описаний алгоритмов и классов нужны идеологические документы. Но в код их не запихнешь, а в состав документации они должны входить.
