суббота, 10 июля 2010 г.

Самодокументируемый код - миф или реальность ?

Для каждого проекта важно иметь документацию. Существует два уровня документации.
Уровень первый или базовый уровень - это комментарии в коде. Также существует документация в виде Wiki, это-следующий уровень. Есть люди которые убеждены что самодокументируемый код не нуждается в комментариях. Идея самодокументируемого кода в том чтобы давать названия переменным и функциям таким образом, чтобы при взгляде на код было понятно как он работает, то есть комментарии как бы не нужны. На своем опыте я убедился что эта идея не работает. Комментарии обязательно нужны. В чем-то защитники самодокументируемого кода правы - автор кода может понять как работает его код. Но другой человек все равно не поймет. Не поймет потому что самодокументируемый код может дать ответ как этот кусок работает. но не даст ответ зачем чем этот кусок был написан, какие ограничения на параметры, поэтому полной картины в голове не будет. Должен быть самодокументируемый код плюс комментарии к нему :)

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

Поэтому проверка наличия комментариев должна быть частью code review. Если нет комментариев значит, на этапе code review код должен быть забракован.

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

3 комментария:

Green FiLin комментирует...

А я бы не был столь однозначен в отношении того, что если человек не пишет комментарии, то и другие виды документации он презирает. Нужно говорит о языке разработки. Например, я очень редко пишу комментарии в коде на 1С. Потому что сама платформа простая и тупая. Тем не менее при помощи это простоты можно наворотить большой и сложный (и непонятный другим) блок и именно поэтому функциональная спецификация - мой основной инструмент. Так же и части пользовательской документации пишу я сам. Парадокс - куча документации и очень мало комментариев.
Хотя, для какого-нибудь C++ или PHP вообщем верно. Каменты рулят!

Sergey Grigoriev комментирует...

Не знаю как 1С, я написал эту статью исходя из моего опыта работы с java и .net

Konstantin Gurnov комментирует...

Очень стоящая на мой взгляд внимания книга затрагивающая тему документации приложения - "Bridging the Communication Gap" by Gojko Adzic. В частности в книге автор описывает методику суть которой Requirements = Examples = Automated Acceptance Tests. Таким образом можно в любое время сделать трейсинг от реквайрементов (которые храняться в вики и тестируются при continuous integration) до кода. Это касается и нефункциональных реквайрементов. Данный подходод поддерживает например такой фреймворк как Fitness.