Как мне убедить моих коллег-разработчиков в том, что они хотят добавить комментарии к коммитам исходного кода?

Я знаю, что Subversion (то, что мы используем на работе) может быть настроен так, чтобы требовать комментариев к коммитам, однако я не в состоянии просто включить это. Я знаю, что моя причина комментировать мои коммиты заключается в том, что полезно, хотя бы в качестве пробежки по памяти, быстро понять причину коммитов. Однако этого недостаточно для борьбы с двумя ответами, которые я всегда получаю:

1. Это занимает слишком много времени, и я просто хочу внести свои изменения в репо.
2. Достаточно просто посмотреть на различия.

Я даже показываю им ценность простого ввода идентификатора проблемы JIRA и того, как он автоматически связывается с проблемой, но все равно не играет с ними.

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

Я знаю, что это правильно, но как я могу заставить их видеть свет? Даже если я не могу убедить своих коллег-разработчиков, как я могу убедить руководство в том, что это правильно для бизнеса?

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

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

Существует также причина одитинга. Обязательные коммиты и идентификаторы тикетов позволяют легко сказать, что все в порядке, мы выдвигаем версию 2, это исправляет дефекты 23, 25, 26 и 27, но нет коммитов для дефекта 24, поэтому он все еще не исправлен.

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

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

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

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

Иногда вам нужно сравнить, но часто нет. Заставить разработчиков сравнивать, когда все, что им нужно было прочитать 2-3 предложения, - это пустая трата времени. Интересно, почему они не видят ценность времени разработчика.

• Подайте хороший пример. Сделайте ваши собственные сообщения о коммитах ярким примером полезности. Включите ссылки на любые другие системы, которые ваша команда использует для управления историями и дефектами. Приведите краткое изложение, обобщающее изменение, и хорошее объяснение того, почему изменение необходимо, а не что-то еще в каждом представлении.
• Всякий раз, когда отсутствие сообщения о приличной фиксации вызывает у вас дополнительную работу, задайте вопрос отправителю. Будьте настойчивы с этим (но не придурком).
• Если это не выходит за рамки вашей роли, напишите сценарий, который ежедневно отправляет журнал изменений, используя сообщения фиксации. Это придаст правдоподобности вашему аргументу о том, что полезные сообщения имеют преимущество, помимо просмотра ревизий. Это также может помочь в управлении на вашей стороне, так как они будут видеть изо дня в день, что происходит.
• Определите своих союзников. Надеюсь, есть хотя бы еще один человек, который согласен с вами (возможно, молча не соглашаясь). Найдите этого человека или этих людей и убедите их, чтобы вы не остались одни.
• Когда представится возможность упомянуть, как приличные сообщения о коммитах сэкономили ваше время (или плохие сообщения стоили вам времени), воспользуйтесь им.

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

Это должен быть один из самых странных вопросов, которые я слышал. Люди тратят часы или даже дни на то, чтобы починить что-то, а лишние 2 секунды, чтобы ввести сообщение коммита, слишком долго ?! Я должен сказать, что буду беспокоиться о работе с такими близорукими людьми. Они явно не используют свои инструменты, чтобы даже приблизиться к своему полному потенциалу.

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

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

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

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

У меня была точно такая же проблема, поэтому я добавил хук pre-commit для Subversion, чтобы он не принимал коммиты, которые не начинались с номера пользовательской истории (некоторое базовое сопоставление с образцом для ожидаемого формата).

Ничто не мешает им войти в 000-0000, но однажды только дурацкий дурак соберет число, когда у них там вполне приемлемое число.

Я сделал это, потратив несколько дней, пытаясь найти, в какие сборки входит набор пользовательских историй. Да, это было связано со сбоем процесса в другом месте, но это все еще невероятно ценная информация для отслеживания.

Хорошие комментарии коммитов похожи на любую хорошую документацию, кэш для вашего медленного и неработающего мозга или кэш результатов длительной отладки / анализа / исследования проблем.

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

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

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

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

К сожалению, там, где я работаю, почта автоматически удаляется через 3 месяца, поэтому на практике это не всегда работает.

Ищите прощения, а не разрешения.

Несмотря на резкость, я сделал именно это. У меня было соотношение 50/50 между людьми, поддерживающими и противостоящими, большинство из которых были на одном уровне со мной в группе. Аргументы были: «Меня не беспокоит» и «Какой смысл?». (Обе указывают на апатию и лень, а не на искренние опасения).

Я добавил хук pre-commit, который просто измерял длину строки и выдавал немного юмористическое сообщение, прежде чем отклонить его. Я поместил свое имя в сообщение, чтобы ответственность за «это безобразие» была ясна. Конечно, «оппозиция» может легко удалить ее, но копание в сценариях потребует больше усилий, чем добавление еще одного комментария!

В течение недели я получал сообщения вроде * * (объяснение удалено) или kjhfkwhkfjhw. После этого начали появляться основные сообщения.

Год спустя скептики используют осмысленные комментарии и фактически признают, насколько они были близоруки. Я никогда не смог бы достичь консенсуса, но я, конечно, получил прощение и, возможно, доверие. Это работает, люди используют это.

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

Я обычно убеждаю людей через:

• диалектика с вескими причинами
• подавать пример
• истирание

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

Дополнительные веские причины для комментариев:

• Генерация ChangeLog автоматически из комментариев.
• Журнал аудита для исправления ошибок, дополнения функций. Это полезно как внутри, так и за пределами команды.
• Сделайте коммит более полезным.
• Хватит спрашивать у разработчика, что делает коммит X (после почти каждого коммита).

• Проверьте ваши журналы SVN на что-то неясное, сделанное 6 месяцев назад.
• Задайте несколько вопросов об этой вещи, не сообщая, когда это было сделано
• ???
• прибыль

Как вы заставляете их хотеть добавлять хорошие комментарии?

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

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

Предложите это руководству за закрытыми дверями:

Происходит наихудший сценарий: все разработчики высшего уровня выходят за дверь.

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

Спросите их, что, по их мнению, облегчит их работу по восстановлению истории приложения:

Чтение простого английского коммитов, которые четко описывают меняющееся состояние системы?

Или они предпочли бы посмотреть на различия в коде и самим разобраться?

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

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

Другой способ - объяснить им, что сообщение коммита может быть полезно, чтобы дать подсказку о том, почему что-то реализовано определенным образом. Даже если в сообщении фиксации просто написано «функция X», вы все равно можете получить представление о том, кто его реализовал, чтобы вы знали, с кем поговорить.

Однако этого недостаточно для борьбы с двумя ответами, которые я всегда получаю:

1. Это занимает слишком много времени, и я просто хочу внести свои изменения в репо.
2. Достаточно просто посмотреть на различия.

Вы пытались бросить вызов своим коллегам-разработчикам, чтобы они получали какую-то другую выгоду от размещения комментариев? Можно посмотреть на это с любой из нескольких точек зрения:

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

Что еще нужно рассмотреть, насколько хорошо вы знаете, что ваши коллеги-разработчики управляют, где вы работаете? Если они пытаются сделать 10 вещей вчера, то я могу понять, что они могут не захотеть изменить то, что они считают чем-то, что уже работает. Вы пытаетесь сказать им: «Нет, это не работает?» Если так, то я могу видеть, как они могут быть немного оборонительными или боевыми в этом. Если вы пытаетесь сказать им: «Хотя это может сработать, есть альтернатива, которая может быть лучше ...», тогда у вас может быть шанс. ИМО, если вы придерживаетесь позиции «святее вас», то это вам не поможет.

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

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

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

Однако важно, чтобы они поняли «Почему», как сказал @Kevin, иначе они просто добавят произвольный комментарий.

У вас есть отзывы кода? Одна вещь, которая может помочь, - это установить правило, согласно которому любой коммит или слияние должен просматриваться и утверждаться другим разработчиком. Затем, если вы являетесь рецензентом, вам придется попросить разработчика, делающего обязательство, объяснить вам, что он сделал. Как только он это сделает, вы должны попросить его ввести в комментарий то, что он только что сказал вам. Зачастую, когда невозможно однозначно объяснить сделанные изменения, это означает, что эти изменения не должны были быть сделаны в первую очередь.

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

Когда вы не пишете комментарии, вы неряшливы и недисциплинированы. И если вы настаиваете на том, что вам не нужно писать комментарии, то вы преднамеренно небрежны.

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

Это элемент процесса изменения: попросите менеджера назначить код, разработанный "x", для "Y" для проверки качества только кода, включая проверку качества комментариев.

В моей собственной организации разработчики не имеют права выполнять окончательный контроль качества своего собственного кода и регистрировать его, это должен сделать другой разработчик. Часть проверки качества - это комментарии, поэтому никаких комментариев, никакой регистрации. Мы выполняем большую работу по контракту, где наше «искусство» на самом деле является чьей-то контрактной интеллектуальной собственностью, поэтому другие должны иметь возможность понимать и использовать наш код. Кроме того, бывают случаи, когда проекты возвращаются к нам после долгого перерыва, и мы должны иметь возможность подобрать код спустя 18-24 месяца и понять, почему, где и как мы пришли к артефакту кода перед нами. Это обеспечивает корыстную мотивацию для написания комментариев.

Попросите ваших коллег-разработчиков сделать несколько слияний, посмотреть историю и сравнить несколько файлов из истории.

Скорее всего, они попросят вас оставить комментарии на следующий день.

Вот несколько советов:

1. Не пытайтесь изменить мир. Вы потерпите неудачу.
2. Вместо этого вы должны признать, что все работают немного по-другому. Ни один размер не подходит всем.
3. Требование каких-то определенных шагов к рабочим процессам людей является очень злым. Изменение этих процессов занимает 10 лет. Вы просите их сделать это до следующего срока.
4. Даже простые изменения процесса могут занять много времени.
5. Небольшой комментарий к коммитам слишком мал, чтобы изменить эти процессы.
6. Вы можете предположить, что они делают качественную работу, но должны дать достаточно свободы для выбора шагов самостоятельно. Некоторые обременительные шаги могут не потребоваться для опытных разработчиков.
7. Если вы нянчитесь с новичками, тогда могут потребоваться более сильные процессы, но опытные разработчики не должны заниматься ерундой.
8. Наложение драконовских ограничений на то, как должна выполняться работа, никогда не сработает, это может только замедлить людей (может быть хорошо, если они слишком быстры)
9. Есть много людей, которые думают, что их путь - единственный правильный способ сделать что-то. Надеюсь, ты не один из них.

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

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