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

Разработка*

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

upd 09.10.2011 Спасибо всем за советы! Хук на коммит кода будет идеальным вариантом, буду прорабатывать такое решение. На данном этапе мои хотелки не идут дальше краткого описания класса/методов, «внутри» кода комментарии меня устраивают.

—

7 октября 2011 в 17:03

Tred 2,1

отсортировано по дате по оценке

ответы (11)

afi 7 октября 2011 в 22:22 #

решение

Мы настроили pre-receive хук на главном git репозитории, он проверяет входящие файлы с кодом на соответствие стандартам кодирования, и если что-то не так — push отклоняется.
Вот так :)

круто! ) а можно подробнее? vedmaka, 7 октября 2011 в 22:41

checkstyle называется. Главное не переборщить с фашизмом. 1nd1go, 7 октября 2011 в 22:58

Спасибо! Хороший вариант. Tred, 9 октября 2011 в 18:00

Главное не переборщить с фашизмом. Это шедеврально ))
А можно его еще пересолить, подсластить и сделать диетическим.
Или «фашизм натуральный 70% свежемороженный, без ГМО». Zloy1, 30 марта в 19:44

sHinE 7 октября 2011 в 17:18 #

решение

Выдайте ему на доработку+поддержку код без документации. Пусть почувствует на своей шкуре полезность комментариев.

А, судя по тому, что он определяет стандарты кодирования — то и задачи вы ему поставит не можете :( sHinE, 7 октября 2011 в 17:23

Небольшой проект, и герой вопроса — в одном лице архитектор-лид-ведущий разраб. В этом проекте это он может мне выдать код на доработку, а не я ему )) Tred, 7 октября 2011 в 17:25

ходить и доставать вопросами по каждому мало понятному участку кода без комментариев :) trollsid, 7 октября 2011 в 17:40

+11

angelov 7 октября 2011 в 17:44 #

решение

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

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

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

+17

kk86 7 октября 2011 в 17:55 #

решение

Если код и правда понятен, то зачем заставлять писать лишнее? Если код местами непонятен, аргументированно требуйте комментировать такие места. В качестве аргументов желательно приводить факт непонятности кода другим разработчикам (то есть надо попросить нескольких людей объяснить что делает неизвестный им код за 5-10 минут).

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

Как разработчик могу сказать, что сам противник комментариев, но с оговоркой: неясные моменты всё-таки надо комментировать, если не удаётся переписать. Другое дело, что когда руководство или коллеги начинают продавливать желание видеть комментарии везде, это вызывает раздражение, так как с комментариями жить тяжелее (не буду «баянить» про то, что их непросто поддерживать и т.п.)

Код «внутри», где необходимо, комментарии имеет. Я бы хотел видеть краткое описание классов и методов. Tred, 9 октября 2011 в 18:07

Я не понимаю, зачем Вам нужны краткие описания. Если бы код был ясен, описания не требовались бы. Если код не ясен, то надо добиваться его прояснения, причём комментарии далеко не самый лучший инструмент. Я бы думал о переименовании/переписывании методов и классов в Вашем случае. kk86, 10 октября 2011 в 14:16

Согласен насчет переименовывания. Контекст типа контекст с именем контекст и параметр типа параметр с именем параметр делает обфускацию кода лишней ))

Processor::Processor (my_context ctx, const Parms& parms) :

 base_class (ctx), m_parms (parms) {}

Думаю что если бы было написано по строчке о назначении параметров — дальнейшее сопровождение будет проще.
p.s. Мне нравится подход, что надо документировать не что делает код, а зачем он это делает. Tred, 10 октября 2011 в 19:49

ChemAli 7 октября 2011 в 18:01 #

решение

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

Когда он увидит реальные потери, то (может быть) проникнется. Если не проникнется, то к вышестоящим.

Damaskus 7 октября 2011 в 18:20 #

решение

Код без комментариев в больших и сложных проектах — бомба замедленного действия.
Лично мне, на месте работы сказали:
— мы работаем так, будь добр, к каждому методу больше трех строк сделай /**javadoc*/.
Собственно, если человек охрененно творческий и не любит приравниваться к общим стандартам, то значит что он не держится за место и/или хочет выпедриться.
В крупных же долгосрочных разработках может порушить весь тех процесс, причем разгребать придется скорее всего не ему. Здесь стоит задуматься.

max_rip 7 октября 2011 в 20:44 #

решение

Для начала покажите как он пишет и места кода которые он комментирует сам, а так может и в правду всем все понятно +)

Vumik 7 октября 2011 в 21:08 #

решение

Поговорите с ним и с командой, насколько Вам интересен конечный продукт.
Если продукт по заказу, а в заказе требуется документация (ну знаете такая… на твердых, шуршащих носителях, либо в них переводимая), то тут у него должен быть прямой интерес использовать /** javadoc */ комментарии, для генерации документации.
Если же продукт ваш и вашей команде его поддерживать дальше, то попробуйте донести до него, что в итоге так будет лучше всем после 2-3 лет разработки и обрастания проекта новыми фишками. Определите минимум, например, /** javadoc */ к классу и методам + отдельные комментарии в накрученном коде.

afi 8 октября 2011 в 00:44 #

решение

вот сам хук
code.google.com/p/solo-framework-lib/source/browse/#svn%2Ftrunk%2Fgithook%2Flatest

т.к. мы работаем с PHP, то использовали PHPCodeSniffer для проверки стандартов. Думаю, для java и с++ тоже есть подобные инструменты

javax 8 октября 2011 в 00:51 #

решение

Код должен быть понятен без комментариев.
Писать комментарии надо только там, где без этого нельзя (неочевидные решения, сложные алгоритмы)

Ну это же очевидно. Вопрос стоит в том как заставить писать эти комментарии. afi, 8 октября 2011 в 23:24

AlexZaharow 10 октября 2011 в 15:32 #

решение

А может НЕ писать комменты — это возрастное? Сам их раньше не писал, но однажды прочитал замечательную фразу:

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

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

Полностью поддерживаю. Поддержка недокументированного кода — это боль в жопе. Tred, 10 октября 2011 в 19:20

Только зарегистрированные пользователи могут оставлять комментарии. Войдите, пожалуйста.

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

отсортировано по дате по оценке
ответы (11)

Теги Хабрахабра

Стандартные