Як я переконаю своїх колег-розробників ХОЧАТИ додавати коментарі до початкових кодів?

Я знаю, що Subversion (те, що ми використовуємо на роботі), можна налаштувати так, щоб вимагати коментарів до комітетів, однак я не в змозі просто включити це. Я знаю, що моя причина коментувати свої зобов’язання полягає в тому, що корисно, хоч би як спогад, щоб швидко зрозуміти причину, що стоїть на цьому. Однак цього, здається, недостатньо для боротьби з двома відповідями, які я завжди отримую:

1. Це займає занадто багато часу, і я просто хочу внести свої зміни в репо.
2. Досить просто просто подивитися на різниці.

Я навіть показую їм значення просто ввести ідентифікатор проблеми JIRA і те, як він автоматично прив'язується до проблеми, але все ще не має кісток з ними.

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

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

Зосередьтеся на "Чому". Це все дуже добре, дивлячись на різниці і бачачи, що хтось змінив логічний потік розділу коду чи щось подібне, але чому вони змінили його? Причина зазвичай є в асоційованому квитку (для вас JIRA).

Вони можуть задатися питанням, чому "Чому" важливо, але через 2 роки, коли ви потрапили на помилку, яка є наслідком цієї зміни, знаючи, чому це було зроблено, неймовірно важливо не тільки виправити вашу нову помилку, але і переконатися ви не викликаєте появу старої помилки.

Є також причина аудиту. Прив'язка комітетів та ідентифікаторів квитків робить насправді легко сказати нормально, ми висуваємо Версію 2, це виправляє дефекти 23, 25, 26 і 27, але проти дефекту 24 немає жодних комісій, тому він все ще залишається невирішеним.

Змусьте їх робити злиття і мати справу з підтримкою. Знову, можливо, ви не в змозі цього зробити, але якщо ви виявите, що ви вирішите проблему з попереднього зобов’язання, ввічливо надішліть її через паркан і скажіть. Я не можу сказати, що ви зробили, оскільки немає коментарів, ви внесли ці зміни, щоб розібратися.

Також для злиття гілок. Не впевнений, падає вам це чи ні, але це одна з питань, яку я вважаю коментарями корисною.

Знову ж таки, не у вашому човні, але коли я керував командою програмного забезпечення, я сказав їм, якщо вони добре зауважують, я буду використовувати їх у льові щотижневого звіту про стан. Отримав відмінні зобов’язання після цього, і мені було легше слідкувати за тим, що відбувається як менеджер.

Нам потрібні коментарі до реєстрації з тієї ж причини, що нам потрібні розриви рядків та пробіли в нашому коді. Щоб полегшити відстеження, зрозуміти прочитане та осмислене.

Іноді потрібно порівнювати порівняння, але часто - ні. Змусити розробників порівнювати їх, коли все, що їм було потрібно, було прочитати 2-3 речення - це загальна трата часу. Цікаво, чому вони не бачать значення часу розробника.

• Наведіть хороший приклад. Зробіть власні повідомлення про фіксацію яскравим прикладом корисності. Додайте посилання на всі інші системи, які ваша команда використовує для управління історіями та дефектами. Подайте коротку заяву, що підсумовує зміни, і добре пояснення, чому потрібні зміни, а не щось інше в кожному поданні.
• Кожен раз, коли відсутність гідного повідомлення про прихильність викликає додаткову роботу, киньте запитання представнику. Будьте наполегливі з цим (але не ривком).
• Якщо це не перевищує вашу роль, напишіть сценарій, який надсилає щоденний журнал змін, використовуючи повідомлення фіксації. Це надасть достовірності вашому аргументу про те, що корисні повідомлення мають користь, ніж перегляд ревізій. Це також може допомогти отримати управління на вашу сторону, оскільки вони щодня будуть бачити, що відбувається.
• Визначте своїх союзників. Сподіваємось, що принаймні ще одна особа погоджується з вами (можливо, мовчки не погоджуючись). Знайдіть цю людину чи тих людей і переконайте їх далі, щоб ви не стояли на самоті.
• Коли з'явиться можливість згадати, наскільки пристойні повідомлення про фіксацію заощадили ваш час (або погані повідомлення коштували вам часу), скористайтеся цим.

Не бійтеся бути крикливим колесом. Боротьба зі шкідливими звичками інших людей часто - це війна знущань.

Це повинно бути одним з найбільш химерних питань, які я чув. Люди витрачають години або навіть дні на те, щоб щось виправити, і зайві 2 секунди для набору повідомлення про фіксацію занадто довго ?! Треба сказати, що я б переймався роботою з такими недалекоглядними людьми. Вони, очевидно, не використовують свої інструменти, щоб навіть наблизитися до свого повного потенціалу.

Ось приклад з огляду коду, до якого я брав участь минулого тижня. Наше програмне забезпечення для управління версіями не зберігає історію в злиттях, тому для старих змін потрібно знайти точну гілку, в якій вона була зроблена, інакше повідомлення про фіксацію показує щось на кшталт "об'єднане з гілкою Y". Гілка Y може показувати "об'єднану з гілкою Z", а гілка на кілька рівнів вкладення глибше насправді має справжнє повідомлення про фіксацію.

Новий працівник не знав, як правильно відслідковувати історію, а це означає, що він по суті працював із тільки різницями. Він побачив якийсь коментований код, пов’язаний із помилкою, яку він відстежував. Коли він прокоментував код, його помилка пішла. Він припускав, що хтось прокоментував код під час налагодження і помилково перевірив його.

Під час огляду коду це було не так, як для нас, тому я відстежив реальне повідомлення про фіксацію та виявив, що існує річна причина для видалення цього коду рік тому. Новий працівник зміг виправити свій код, щоб виправити нещодавно виявлену помилку, не вводячи старого.

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

У мене була точно така ж проблема, тож я додав Subversion гачок, який попередньо здійснює, щоб він не приймав жодних зобов’язань, які не починалися з номера історії користувача (деякий базовий зразок відповідності очікуваному формату).

Ніщо не заважає їм ввести 000-0000, але колись лише ідіотизм, що руйнує, збирається нараховувати номер, коли у них цілком прийнятна кількість.

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

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

Наприклад, кожен раз, коли ви витрачаєте час на щось, з'ясовуючи, наприклад, налагодження, аналіз журналів чи будь-чого іншого, ваші результати та результати є цінними. Звичайно, більшість завдань можна повторити, але це може зайняти час. Тому завжди слід документувати свої результати.

Тим не менш, документація потребує часу, а іноді вона вважається не потрібною, як, наприклад, "ми повинні були зробити це лише один раз, так навіщо її записувати". Це нормально, але як тільки ти робиш те ж саме вдруге, оскільки ти не документував результати вперше, то, звичайно, розумно документувати результати.

Отже, якщо ваші колеги вважають, що надмірно працювати над додаванням коментарів, наприклад, принаймні вказуйте на справу Джира / Квиток, яку вони вирішували, ну вони можуть бути мотивовані тиском постійно відповідати на запитання щодо причини кожного. набір змін.

На мою думку, документація повинна вироблятися як функція інформації, яка запитується. Наприклад, поштова кореспонденція - це досить гарна документаційна система. Запитання отримують відповіді, які можна отримати пізніше, саме так розсилки та форуми працюють на практиці як бази знань.

На жаль, там, де я працюю, пошта автоматично видаляється через 3 місяці, тому це не завжди працює на практиці.

Шукайте прощення, а не дозволу.

Поки суворий, я робив саме це. У мене був розкол 50/50 між підтримуючими людьми та людьми, які виступають проти, більшість з яких були на тому ж рівні, що і я в групі. Аргументи були "я не можу турбуватися" і "в чому сенс?". (Обидва вказують на апатію та лінь, а не на справжні побоювання).

Я додав гачок перед фіксацією, який просто виміряв довжину струни і дав злегка жартівливе повідомлення, перш ніж відкинути її. Я вказав своє ім’я в повідомленні, щоб відповідальність за "це обурення" була чіткою. Звичайно, "опозиція" може легко її зняти, але копатись до сценаріїв потрібно більше зусиль, ніж додавання ще одного коментаря!

Протягом тижня я отримував повідомлення типу * * (додаткове видалення) або kjhfkwhkfjhw. Після цього основні повідомлення почали з’являтися.

Рік і скептики використовують значущі коментарі і фактично визнають, наскільки вони були недалекоглядними. Я ніколи не міг отримати консенсус, але я, безумовно, отримав прощення і, можливо, довіру. Це працює, люди ним користуються.

Якщо ви хотіли бути більш пристойними (або відчуваєте, що у вас виникнуть проблеми), попросіть дозволу додати гачок для здійснення випробувань протягом пробного періоду. Скажіть, що якщо людям це не сподобається через 2 тижні чи 4 тижні, ви вийдете. Швидше за все, вони втратять інтерес ... або виростуть до вподоби.

Я зазвичай переконую людей через:

• діалектика з вагомими опорними причинами
• ведучи за прикладом
• виснаження

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

Додаткові вагомі причини для коментарів:

• Генерування ChangeLog автоматично з коментарів.
• Слід аудиту для виправлень помилок, доповнень для функцій. Це корисно як в команді, так і поза нею.
• Зробіть поштову скриньку кориснішою.
• Не дозволяйте мені запитувати розробника, що робить X (після майже кожного виконання).

• Перевірте, чи у вас є журнали SVN на щось незрозуміле, зроблене 6 місяців тому.
• Задайте кілька запитань щодо цієї речі, не повідомляючи, коли це зроблено
• ???
• Прибуток

Як ви їх хочете додати хороші коментарі?

З досвіду роботи з колегою я просто мав. Наприкінці проекту нам довелося написати зведений документ про всі зміни, внесені протягом проекту. Не зробивши належних записів на виконання зобов’язань, мій колега вважав це завдання досить трудомістким, і тепер перейшов до коментувати досить тривалі коментарі з кожним зобов’язанням.

Отже - винос - одним із рішень може бути, щоб розробники писали підсумкові документи в кінці проекту, де було детально описано, які зміни були внесені в які файли, які файли були додані / вилучені та чому.

Запропонуйте це керівництву за закритими дверима:

Найгірший сценарій трапляється: всі розробники вищого рівня виходять за двері.

Поки компанія намагається заповнити порожні місця для розробників, команда керівництва покладається на завдання донести стан системи до клієнта.

Запитайте їх, що вони думають, що полегшить їх роботу в реконструкції історії програми:

Читання звичайної англійської мови, що чітко описує мінливий стан системи?

Або вони вважають за краще дивитися на різницю в коді та розбирати їх самі?

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

Наприклад, скажімо, що вони працюють над наступною проблемою: У них помилка, яка якось з'явилася, коли було реалізовано чергове виправлення помилок для того ж коду (о, іронія). Здобути це можна було б просто за допомогою пошуку файлів повідомлення (і таким чином з'ясувати, хто це написав).

Іншим способом було б пояснити їм, що повідомлення про фіксацію може бути корисним, щоб дати підказку, чому щось було реалізовано певним чином. Навіть якщо повідомлення про фіксацію просто говорить "особливість X", ви все одно можете зрозуміти, хто його реалізував, тож ви знаєте, з ким спілкуватися.

Однак цього, здається, недостатньо для боротьби з двома відповідями, які я завжди отримую:

1. Це займає занадто багато часу, і я просто хочу внести свої зміни в репо.
2. Досить просто просто подивитися на різниці.

Чи намагалися ви кинути виклик своїм колегам-розробникам, щоб вони отримали якусь іншу користь від коментарів? На це можна було поглянути з будь-якого з кількох кутів:

1. Підвищення їхньої гри - Це може бути складнішою перспективою, але ідея тут полягає в тому, що вони роблять це протягом певного періоду часу і звикають до ідеї, так що звичка полягає в тому, що потрібно піти іншим шляхом. Ще один момент - скільки пильної уваги отримають коментарі? Якщо ви хочете короткого оповідання в коментарі, я міг би зрозуміти їхню думку.
2. Субсидіювання змін - саме тут у вас буде якийсь конкурс, як спосіб здійснити початкову покупку, щоб спробувати це або запропонувати якийсь інший стимул, щоб зміни були здійснені на деякий час.

Щось ще слід врахувати - наскільки добре ви знаєте, чим керують ваші колеги-розробники, де ви працюєте? Якщо вони намагаються зробити 10 справ вчора, то я можу зрозуміти, що вони можуть не хотіти змінювати те, що вони бачать як щось, що вже працює. Ви намагаєтесь сказати їм: "Ні, це не працює?" Якщо так, то я бачу, наскільки вони можуть бути дещо захисними чи бойовими. Якщо ви намагаєтесь сказати їм: "Хоча це може спрацювати, є альтернатива, яка може бути кращою ...", тоді у вас може бути шанс. Маючи тут відношення «Холіє, ніж ти», тобі не допоможе, ІМО.

Інший спосіб дивитися на це як спосіб для розробника (ів) , що беруть участь у розвитку їхньої кар'єри - вони повинні володіти в документації їх роботи.

На додаток до інших пунктів, зазначених у вищезгаданій статті, існує можливість перегляду змін коду, щоб з’ясувати, де / коли / чому було здійснено зміну. Це може бути життєво важливим при відстеженні невловимого помилки.

Після того, як ви переконали їх у важливості коментувати свої зобов'язання, ви можете створити сценарій, який змушує коментувати коміти, інакше це не вдасться. Ви навіть можете вказати мінімум символів, щоб забезпечити його змістовний коментар. Це допоможе їм «запам'ятати».

Однак важливо, щоб вони зрозуміли, чому так сказав @Kevin, інакше вони просто додадуть випадковий коментар.

У вас є кодові огляди? Одне, що може допомогти - це встановити правило, згідно з яким будь-яке введення чи об'єднання повинно бути розглянуте та затверджено іншим розробником. Тоді, якщо ви рецензент, вам доведеться попросити розробника, який взяв на себе зобов'язання, пояснити вам, що він зробив. Як тільки він це зробить, вам слід попросити його вписати в коментар те, що він вам щойно сказав. Часто, коли не можна послідовно пояснити внесені зміни, це означає, що ці зміни не повинні були бути внесені в першу чергу.

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

Коли ви не пишете коментарів, ви неохайні і недисципліновані. І якщо ви наполягаєте на тому, що не потрібно вимагати писати коментарі, то ви навмисно недбалі.

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

Це пункт зміни процесу: Запропонуйте менеджеру присвоїти код, розроблений "x" до "Y", для перевірки якості лише одного коду, включаючи QA коментарів.

В моїй власній організації розробникам заборонено виконувати остаточну якість власного коду та перевіряти його, це повинен зробити інший розробник. Частина перевірки якості - це коментарі, тому жодних коментарів, жодної реєстрації. Ми робимо багато контрактних робіт, коли наше "мистецтво" насправді є чужою контрактною інтелектуальною власністю, тому інші повинні вміти розуміти і використовувати наш код. Крім того, бувають випадки, коли проекти повертаються до нас після тривалої перерви, і нам потрібно мати змогу забрати код через 18-24 місяці і зрозуміти, чому, де і як ми прибули до артефакту коду перед нами. Це забезпечує корисну користь для написання коментарів.

Попросіть і попросіть своїх колег-розробників зробити кілька об'єднань та переглянути історію та порівняти кілька файлів з історії.

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

Ось кілька порад:

1. Не намагайтеся змінити світ. Ви провалиться.
2. Натомість слід усвідомити, що всі працюють трохи по-іншому. Жоден розмір не підходить усім.
3. вимагати певних кроків до трудових процесів людей - це дуже зло. Зміна цих процесів займає 10 років. Ви просите їх зробити це до наступного терміну.
4. Навіть прості зміни процесу можуть зайняти багато часу.
5. Деякі невеликі коментарі до комітетів є занадто незначними, щоб змінити ці процеси.
6. Можна припустити, що вони працюють якісно, ​​але повинні дати достатню свободу для вибору самих кроків. Деякі обтяжливі кроки, можливо, не знадобляться досвідченим розробникам.
7. Якщо ви займаєтесь нянями-новачками, то, можливо, знадобляться більш сильні процеси, але досвідчені розробники не повинні мати справу з фігнями.
8. Накладення драконівських обмежень щодо того, як треба виконувати роботу, ніколи не буде працювати, це може лише уповільнити людей (може бути добре, якщо вони занадто швидкі)
9. Є багато людей, які думають, що їхній шлях є єдиним правильним способом зробити справи. Сподіваюся, ви не один з них.

Якщо ваш джерело контролює це, увімкніть обов'язкові коментарі, щоб запобігти будь-яким коментарям, що не коментуються. Досить просто і всі незабаром зрозуміють, що 5 секунд набору коментаря безболісне.

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