Должен ли один программист документировать код другого?

Question

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

Их аргументы:

1. У вас будет два программиста, знакомых со всем.
2. Это парное программирование, вроде.
3. Это более рентабельно = они сделают больше.
4. Это демонстрирует, что их код читабелен и доступен для обслуживания.
5. Они будут рады ответить на любые вопросы; так что это форма наставничества.

Однако число программистов, которых они заняты, чтобы оставаться в курсе, кажется, со временем увеличивается.

Это хорошая идея?

---

Вау! Это так не наш опыт!

Вот некоторые пояснения, которые оказываются важными.

1. Старшие разработчики - рефлексивные самодокументирующие. Это основной вопрос найма. Иногда им нужно сказать «оставь это младшему парню».

2. Это рассматривается как инструмент проверки для старшего парня (и наши младшие парни нанимаются с, я думаю, довольно высокой планкой, чтобы очистить).

3. Да, код должен быть одноцелевым и самодокументируемым. Если младший парень не может прокомментировать это, это обратная связь, к которой старшие относятся серьезно.

4. Предполагается, что юниоры будут относиться к нему как к упражнению по рефакторингу, и оно работает таким образом чаще, чем вы ожидаете. Особенно ловить такие вещи, как проблемы ЯГНИ, чрезмерный размах и т. Д. Они попадают в перекрестие своих старших. На самом деле, они произошли изменения. (Если они действительно начнут возражать, мы откажемся от этого. Старшие более чем готовы приспособиться - они понимают, что они больше, чем кто-либо другой, ответственны за успехи юниоров.)

5. Разве ваши старшие люди не хотят объяснить их код?

6. Мы твердо привержены принципу Agile «каждый владеет кодом». Мы думаем, что это ускоряет процесс.

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

Может быть, мы отфильтруем несколько младших кандидатов, потому что проясним, что именно так мы и работаем. Но это не проблема оборота. (Но прошло всего 3 месяца.)

Answer 1

Наверное, не такая уж хорошая идея. По ряду причин:

• У лидов меньше стимулов для написания правильного кода, если есть строка младших, которые будут "вычищать" их. Будь то с документами или иным образом. Я никогда не видел, чтобы стимул к снижению качества оставался без ответа.

• Если руководители команд с удовольствием ответят на вопросы, почему бы просто не ответить на вопросы в сеансе сопряжения? На самом деле это займет меньше времени, потому что вы сможете сразу же ответить на вопрос, не пытаясь вспомнить, что вы делали на прошлой неделе.

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

• Код должен быть «самодокументированным». Такие вещи, как Javadoc и т. Д. В последние годы вышли из моды, потому что это мало что дает (это всегда устарело и т. Д.). Гораздо разумнее тратить время на реструктуризацию кода, чтобы его было легко понять.

• Я не покупаю «более продуктивный» аргумент. Если у вас есть 5 старших, работающих на полной скорости, и 5 юниоров, которые занимаются за ними, у вас есть только 5 разработчиков, создающих код. Если у вас есть 10 разработчиков, движущихся со скоростью 2/3, у вас будет большая общая емкость (~ 6 разработчиков на полной скорости).

Answer 2

Это не ужасная идея. Чтение хорошего кода - это хороший способ научиться, и быть уверенным, что вы можете написать код, за которым кто-то другой может следовать достаточно хорошо, чтобы комментировать, это полезно.

Но вашим старшим разработчикам все равно нужно будет прочитать и проверить правильность комментариев, или это просто пустая трата времени.

И значение для младшего разработчика ограничено по времени. Я бы сказал, самое большее за 6 месяцев до того, как для юниора не будет никакой реальной ценности, и еще меньше времени, прежде чем вы рискуете потерять (теперь обученного) младшего в более удовлетворительной работе.

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

Answer 3

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

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

Answer 4

Вау !! Я единственный, кто считает, что время документирования кода до вы начинаете стучать по клавишам?

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

Есть ли у вас процессы? SQA?

Answer 5

Чтобы ответить на заглавный вопрос,

Если один программист задокументирует код другого

Я документирую код, который смотрю, когда я понимаю, что он делает.

Мне все равно, кто это написал.

Answer 6

Если они напишут четко переработанный код, у них будет очень мало комментариев, если они вообще есть.

Answer 7

Я не достаточно умен, чтобы написать собственный ответ, поэтому я процитирую людей умнее меня:

Джоэл сказал :

ДонДаже не пытайтесь сказать выпускникам колледжа CS, что они могут работать на вас, но «каждый должен немного постараться в QA, прежде чем переходить к коду».Я видел много этого.Программисты не делают хороших тестеров, и вы потеряете хорошего программиста, которого гораздо сложнее заменить.

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

Yegge сказал :

Ученик UW, с которым я только что беседовал, сказал мне, что его друг проходил стажировку в Intel этим летом, и ненавидел его так сильно, что отказался от довольно выгодного предложения от них на полный рабочий день.Друг сказал, что он убежден, что сотрудник Intel написал сценарий для фильма Office Space.Мало того, что люди там имеют 5 или 6 боссов, что достаточно плохо;у них действительно есть отчеты TPS, и каждый должен их делать.И когда они меняют формат титульной страницы, выходит заметка, сообщающая всем об этом.

Хотя это, вероятно, один из самых сюрреалистических опытов прохождения практики, о которых я слышал, ужасы-истории про практику довольно распространены.И дело не в том, что стажер никому не рассказывает в школе.Слово быстро обходит.Многие компании занесли себя в черный список в крупных университетах.Студент UW, который рассказал мне историю, говорит, что теперь никто из отдела CS не заинтересован в работе в Intel.Intel все еще набирает, как сумасшедший в университетском городке, но они фактически закрыли конвейер.

Короче, если вы заставите начинающих разработчиков не хотеть там работать, они ... там не будут работать,Если у вас нет младших разработчиков, в конце концов у вас не будет старших разработчиков, а потом вообще никаких разработчиков, если вы поймете, что у меня есть дрейф.

Единственное возможное объяснение, то, что вы, хорошийСэр / мадам, работа в Google и проблема фактическая в том, что найм лучших талантов стал слишком легким, и скрытый мотив заключается в том, что они хотят выровнять игровое поле для небольших компаний.(Никто другой не осмелится сделать что-то, что затруднит найм хороших талантов.) И в этом, я желаю вам всем удачи в мире, потому что моя компания - не Google, и мы хотели бы, чтобы более квалифицированные кандидаты шли через наши двери..

Answer 8

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

Answer 9

Это лучше, чем не документировать код. Если вы собираетесь это сделать, я постараюсь расширить роль. Попытайтесь бросить вызов разработчикам, чтобы найти ошибки, улучшить код (опасно, но с помощью руководства), написать контрольные примеры и все, что нужно было сделать в первый раз.

Установите какой-либо тип стимула для большинства проблем, которые может найти младший. Призывает младшего выглядеть сложнее и заставляет лидера немного подумать, прежде чем выполнять свои основные обязанности при написании кода.

Answer 10

Это действительно «зависит», вам нужно задокументировать конкретные цели этого процесса и затем измерить результат. Возможно, это просто модель снижения затрат, когда менее оплачиваемые сотрудники выполняют больше необходимой работы. Вы также можете привести и другие значения, которые вы привели в качестве примеров, и их сложнее измерить (т.е. действительно ли документер получает знания, которые они могут использовать). Суть в том, что нет правильного ответа на подобные вопросы, поскольку он прагматичен по своей природе, то есть последствия этого действия будут оправдывать (или иным образом) его существование.