Де-факто стандарт в індустрії вимагає писати коментарі до кожного коміту. Часто ще потрібно також вказувати номер тікету, в рамках якого був зроблений цей коміт.
В попередньому пості ми обговорили чому потрібно дотримуватися внутрішніх порядків компанії (tl;dr: бо інакше ви станете проблемою та вас позбудуться), але мотивація робити це чисто KPI-на — якщо вас оцінюють за критерієм «пересування тасок», то логічно цей показник тримати високим.
А якщо компанія не має регламенту? Чи має бути в інженера мотивація писати грамотні коментарі до комітів і працювати з системами управління проєктами?
Найяскравіший приклад такої ситуації це клієнти Телеграму: в андроїд клієнті ви не побачите жодного коментаря до коміту. Раніше це були просто «fixes», зараз більш пристойні «Update to X.X.X». Автор апки написав коментар, що він не має наміру витрачати час на коменти, бранчі, теги та інше: «I don't want to waste time to writing tags, commit comments, etc.» Коментар був зроблений 7 років тому, і тоді він виправдовував це тим, що не знав, що код заопенсорсять, але ситуація не змінилась.
macOS клієнт теж не радує зрозумілими дескріпшенами. Лаконічне «fixes», втім, деколи змінює «video calls» або «audio player».
Наступного разу, коли в компанії вам вкажуть на пустий дескріпшн, покажіть їм ці репозиторії, скажіть „ось люди роблять найкращий у світі месенджер і не пишуть коментарів, шах і мат, джиропівні”, та сміливо пуште свої зміни прямо в мейн.
Головне пам'ятати: correlation ≠ causation. Те, що розробник телеграму не пише коментарів, не значить що завдяки цьому телеграм клієнт хороший. Якщо ви перестанете писати коменти, то це не значить, що ваш софт стане кращим. Швидше навпаки.
Мотивація писати коментарі в розробника одна — якщо над кодобазою працює декілька людей. В наведених прикладах абсолютну більшість комітів зробила одна людина. Як тільки ви додаєте у проєкт ще когось, відразу виникає питання, як зрозуміти, які зміни були зроблені. Дивитися діфф кожного коміту — високе когнітивне навантаження, а опис хоч приблизно дає зрозуміти що відбувається.
Також не знаємо, скільки часу змарнували люди з телеграму через пусту історію. Можливо, ніскільки, тому що коли працюєш над одним проєктом, то він постійно знаходиться в голові, а може й багато — цього ми не дізнаємося.
Гаразд, з описом розібралися, але навіщо потрібні номери тікетів в історії комітів? Припустимо, у вас є тікет, як зрозуміти, він зроблений у версії X? Якщо номер тікета в коменті не зафіксований в коміт меседжі, то про відповідну відмітку на багтрекері має подбати програміст, але це можна забути. А от якщо вказати номер тікету в коміті, то він автоматично підтягнеться в багтрекер і по історії відразу буде зрозумілим, що й куди потрапило.
Часто в мене була ситуація, коли я знаходжу проблему в опенсорсній лібі й попадаю на багтрекер. Якщо баг вже виправили, то там з високою ймовірністю буде вказана версія де це відбулось, або через коміт, або через коміт та коментар у тікеті. Якби замість історії я бачив «fixes», то мені залишалося б тільки оновлюватися на останню версію та сподіватися що нічого не зламається.
Якщо працювати одному, то уявіть що в майбутньому до вас додасться людина, або ви передасте кодобазу в інше місце. У ваших же інтересах зробити артефакт репозиторію максимально зрозумілим для інших. Хороша історія комітів, тікети й так далі чудово допомагають.
Тому я пишу історію навіть на пет-проєктах, які нікому не показую. Раджу вам робити те саме.
P.S.: інші телеграм клієнти ведуть ±нормальну історію, хоча там теж майже всюди 1 розробник.
Сподобалось? Долучайтеся до мого телеграм каналу: https://t.me/full_of_hatred
