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

Question

[Tred]

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

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

Comments

[ChemAli]

А стандартов кодирования нету? Или есть, но он имеет возможность их игнорировать?

[Tred]

Он как раз то лицо, которое определяет стандарты кодирования.

[Masterkey]

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

Answer 1

[afi]

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

Comments

[Lakewake]

круто! ) а можно подробнее?

[1nd1go]

checkstyle называется. Главное не переборщить с фашизмом.

[Tred]

Спасибо! Хороший вариант.

[Zloy1]

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

Answer 2

[kk86]

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

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

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

Comments

[Tred]

Код «внутри», где необходимо, комментарии имеет. Я бы хотел видеть краткое описание классов и методов.

[kk86]

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

[Tred]

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

Processor::Processor (my_context ctx, const Parms& parms) :
base_class (ctx), m_parms (parms) {}

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

Answer 3

[angelov]

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

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

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

Answer 4

[Антон]

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

Comments

[Антон]

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

[Tred]

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

[trollsid]

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

Answer 5

[max_rip]

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

Answer 6

[javax]

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

Comments

[afi]

Ну это же очевидно. Вопрос стоит в том как заставить писать эти комментарии.

Answer 7

[ChemAli]

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

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

Answer 8

[Damaskus]

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

Answer 9

[Vumik]

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

Answer 10

[afi]

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

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

Answer 11

[Alex XYZ]

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

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

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

Comments

[Tred]

Полностью поддерживаю. Поддержка недокументированного кода — это боль в жопе.

Answer 12

[afiskon]

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