Что делать с человеком, который не комментирует код?

Пятнишный такой вопрос. Есть талантливый разработчик, который не документирует код, или делает это в очень незначительных количествах, потому, что «у меня нет на это времени» и «всё понятно из кода». По ряду причин мер административного воздействия к нему применить нельзя. Но есть желание найти такие аргументы, чтобы склонить этого человека документировать свой код. С удовольствием изучу ваши предложения.

upd 09.10.2011 Спасибо всем за советы! Хук на коммит кода будет идеальным вариантом, буду прорабатывать такое решение. На данном этапе мои хотелки не идут дальше краткого описания класса/методов, «внутри» кода комментарии меня устраивают.
  • Вопрос задан
  • 3719 просмотров
Решения вопроса 1
afi
@afi
Мы настроили pre-receive хук на главном git репозитории, он проверяет входящие файлы с кодом на соответствие стандартам кодирования, и если что-то не так — push отклоняется.
Вот так :)
Ответ написан
Пригласить эксперта
Ответы на вопрос 11
kk86
@kk86
Если код и правда понятен, то зачем заставлять писать лишнее? Если код местами непонятен, аргументированно требуйте комментировать такие места. В качестве аргументов желательно приводить факт непонятности кода другим разработчикам (то есть надо попросить нескольких людей объяснить что делает неизвестный им код за 5-10 минут).

Если я правильно понял, то в вашем случае человек «особенный» в некоторых смыслах. В частности, его нельзя заставить делать так, как Вы хотите. Поэтому тут следует попытаться убедить человека или, как крайний вариант, прийти к компромиссу.

Как разработчик могу сказать, что сам противник комментариев, но с оговоркой: неясные моменты всё-таки надо комментировать, если не удаётся переписать. Другое дело, что когда руководство или коллеги начинают продавливать желание видеть комментарии везде, это вызывает раздражение, так как с комментариями жить тяжелее (не буду «баянить» про то, что их непросто поддерживать и т.п.)
Ответ написан
angelov
@angelov
Заепывайте его почаще по каждым мелочам и по нескольку раз, если отсутствие документации создает вам трудности, чтобы он понял, что лучше описать один раз, чем 10 раз объяснять. Звоните в субботу ночью, в 5 утра, во время обеда и т.д.

Главное не переборщить, чтобы, если это его власти, не возникла мысль уволить/заменить на менее любопытного работника.

Ну а если отсутсвие комментариев на вашей работе никак не сказывается, то, разумеется, понять и простить. Некоторые разработчики не комментят код, считая, что у них он и так как роман Дюме написан, иногда некоторые из них правы. А документировать так вообще без пинка мало кто любит
Ответ написан
Комментировать
sHinE
@sHinE
веб-разработчик, php/js/mysql и сопутствующее
Выдайте ему на доработку+поддержку код без документации. Пусть почувствует на своей шкуре полезность комментариев.
Ответ написан
@max_rip
Для начала покажите как он пишет и места кода которые он комментирует сам, а так может и в правду всем все понятно +)
Ответ написан
Комментировать
javax
@javax
Software Architect, Java Developer since 1996
Код должен быть понятен без комментариев.
Писать комментарии надо только там, где без этого нельзя (неочевидные решения, сложные алгоритмы)
Ответ написан
@ChemAli
Возьмите под наблюдение его код на неделю и посчитайте все случаи, когда код вызвал затруднения. Также посчитайте время, которое было потрачено на объяснения и вызвало простои. переведите в деньги и представьте ему расчет. Типа, если бы потратил на комментарий минуту здесь, то вот здесь мы бы не потеряли 5000 рублей и 2 часа времени. Ты, мол, приносишь убытки тем, что не комментируешь код.

Когда он увидит реальные потери, то (может быть) проникнется. Если не проникнется, то к вышестоящим.
Ответ написан
Комментировать
Damaskus
@Damaskus
Код без комментариев в больших и сложных проектах — бомба замедленного действия.
Лично мне, на месте работы сказали:
— мы работаем так, будь добр, к каждому методу больше трех строк сделай /**javadoc*/.
Собственно, если человек охрененно творческий и не любит приравниваться к общим стандартам, то значит что он не держится за место и/или хочет выпедриться.
В крупных же долгосрочных разработках может порушить весь тех процесс, причем разгребать придется скорее всего не ему. Здесь стоит задуматься.
Ответ написан
Комментировать
@Vumik
Поговорите с ним и с командой, насколько Вам интересен конечный продукт.
Если продукт по заказу, а в заказе требуется документация (ну знаете такая… на твердых, шуршащих носителях, либо в них переводимая), то тут у него должен быть прямой интерес использовать /** javadoc */ комментарии, для генерации документации.
Если же продукт ваш и вашей команде его поддерживать дальше, то попробуйте донести до него, что в итоге так будет лучше всем после 2-3 лет разработки и обрастания проекта новыми фишками. Определите минимум, например, /** javadoc */ к классу и методам + отдельные комментарии в накрученном коде.
Ответ написан
Комментировать
afi
@afi
вот сам хук
code.google.com/p/solo-framework-lib/source/browse/#svn%2Ftrunk%2Fgithook%2Flatest

т.к. мы работаем с PHP, то использовали PHPCodeSniffer для проверки стандартов. Думаю, для java и с++ тоже есть подобные инструменты
Ответ написан
Комментировать
AlexXYZ
@AlexXYZ
O Keep Clear O
А может НЕ писать комменты — это возрастное? Сам их раньше не писал, но однажды прочитал замечательную фразу:

«Программы пишутся для людей, а не для компьютеров.»

С тех пор их и пишу. Код, конечно, должен быть понятен без комментариев, но на хорошо документированном коде можно учиться. Мало ли кому код в руки попадёт, зато другой человек спасибо скажет.
Ответ написан
afiskon
@afiskon
Он по-своему прав. Если нормально писать, то в большинтсве случаев все действительно понятно из кода. А комментарии только место занимают, да еще и со временем начинают вводить читающих их людей в заблуждение, если с кодом разъехались. Но если это часть корпоративной культуры, то просто не принимать pool request без комментариев, вот и все. Либо начнет писать комментарии, либо не будет делать фичей и вылетет "за неуспеваемость", тут уже ему решать.
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы