Jak przekonać innych programistów do WANT, aby dodali komentarze do zatwierdzeń kodu źródłowego?

Wiem, że Subversion (to, czego używamy w pracy) można skonfigurować tak, aby wymagało komentarzy na temat zatwierdzeń, ale nie jestem w stanie po prostu włączyć tego. Wiem, że moim powodem do komentowania moich zatwierdzeń jest to, że przydatne, choćby jako pamięć-jogger, jest szybkie zrozumienie przyczyny zmiany. Nie wydaje się to jednak wystarczające, aby zwalczyć dwie odpowiedzi, które zawsze otrzymuję:

1. Trwa to zbyt długo i chcę tylko wprowadzić zmiany w repozytorium.
2. Wystarczy spojrzeć na różnice.

Pokazuję im nawet wartość dodania identyfikatora problemu JIRA i sposób, w jaki automatycznie wiąże się on z problemem, ale nadal nie ma z nimi kości.

Co najgorsze, osoba, która może zadzwonić, znajduje się w tym samym obozie: nie chce zawracać sobie głowy i nie ma nic przeciwko patrzeniu na różnice.

Wiem, że to jest właściwe, ale jak mogę sprawić, by widzieli światło? Nawet jeśli nie jestem w stanie przekonać innych programistów, jak mogę przekonać kierownictwo, że jest to dobra rzecz dla biznesu?

Skoncentruj się na „Dlaczego”. Wszystko bardzo dobrze wygląda na różnice i widzi, że ktoś zmienił logiczny przepływ części kodu lub coś w tym rodzaju, ale dlaczego to zmienił? Dlaczego zwykle znajduje się w powiązanym bilecie (JIRA dla Ciebie).

Mogą się zastanawiać, dlaczego „Dlaczego” jest ważne, ale za 2 lata, kiedy złapałeś jakiś błąd, który jest efektem domniemanej zmiany, wiedza o tym, dlaczego zostało to zrobione, jest niezwykle ważna nie tylko dla usunięcia nowego błędu, ale również upewnienia się, że nie powoduje to ponownego pojawienia się starego błędu.

Istnieje również powód kontroli. Wiązania zatwierdzeń i identyfikatory biletów sprawiają, że naprawdę łatwo powiedzieć, wypychamy wersję 2, to naprawia defekt 23, 25, 26 i 27, ale nie ma żadnych zatwierdzeń przeciwko defektowi 24, więc nadal jest zaległy.

Niech wykonają połączenia i zajmą się wsparciem. Ponownie może nie jesteś w stanie tego zrobić, ale jeśli znajdziesz rozwiązanie problemu z poprzedniego zatwierdzenia, prześlij go uprzejmie przez ogrodzenie i powiedz. Nie mogę powiedzieć, co zrobiłeś, ponieważ nie ma komentarzy do zatwierdzenia, wprowadziłeś zmiany, które musisz wymyślić.

Również do łączenia oddziałów. Nie jestem pewien, czy to Cię dotyczy, czy nie, ale to jest jeden obszar, w którym uważam komentarze za przydatne.

Znowu, nie na twojej łodzi, ale kiedy zarządzałem zespołem programistów, powiedziałem im, czy robią dobre komentarze, wykorzystam je jako tygodniowy raport o stanie. Po tym otrzymałem doskonałe zobowiązania i łatwiej było mi śledzić, co się działo jako menedżer.

Potrzebujemy komentarzy do odprawy z tego samego powodu, dla którego potrzebujemy podziału linii i odstępów w naszym kodzie. Aby ułatwić śledzenie, zrozum czytanie i zrozumienie.

Czasami musisz porównywać, ale często nie. Zmuszenie deweloperów do porównania, kiedy wszystko, czego potrzebowali, to przeczytanie 2-3 zdań, to całkowita strata czasu. Zastanawiam się, dlaczego nie widzą wartości czasu programisty.

• Stanowić dobry przykład. Stwórz własne komunikaty zatwierdzania jako świetny przykład przydatności. Dołącz odniesienia do wszelkich innych systemów używanych przez zespół do zarządzania historiami i defektami. Umieść krótkie oświadczenie podsumowujące zmianę i dobre wyjaśnienie, dlaczego zmiana jest konieczna, a nie coś innego w każdym zgłoszeniu.
• Ilekroć brak komunikatu o przyzwoitym zatwierdzeniu powoduje dodatkową pracę, zadaj pytanie autorowi. Bądź wytrwały z tym (ale nie palantem).
• Jeśli nie przekroczysz swojej roli, napisz skrypt, który wysyła dziennik zmian za pomocą komunikatów zatwierdzania. Zapewni to wiarygodność argumentu, że przydatne wiadomości mają tę zaletę, że nie przeglądają wersji. Może to również pomóc w zarządzaniu po twojej stronie, ponieważ będą oni z dnia na dzień widzieć, co się dzieje.
• Zidentyfikuj swoich sojuszników. Mamy nadzieję, że jest co najmniej jedna osoba, która się z tobą zgadza (być może po cichu nie zgadzając się). Znajdź tę osobę lub osoby i przekonaj ich dalej, abyś nie stał sam.
• Kiedy pojawi się okazja, aby wspomnieć, jak dobre komunikaty o zatwierdzeniu zaoszczędziły Twój czas (lub złe wiadomości kosztowały Twój czas), skorzystaj z niego.

Nie bój się być skrzypiącym kołem. Zwalczanie złych nawyków innych ludzi jest często wojną na wyczerpanie.

To musi być jedno z najdziwniejszych pytań, jakie słyszałem. Ludzie spędzają godziny, a nawet dni naprawiając coś, a dodatkowe 2 sekundy na wpisanie komunikatu zatwierdzenia są zbyt długie ?! Muszę powiedzieć, że martwiłbym się pracą z tak krótkowzrocznymi ludźmi. Oczywiście nie używają swoich narzędzi, aby zbliżyć się do pełnego potencjału.

Oto przykład z przeglądu kodu, w który byłem zaangażowany w zeszłym tygodniu. Nasze oprogramowanie do kontroli wersji nie zachowuje historii podczas scalania, więc w przypadku starszych zmian musisz znaleźć dokładną gałąź, w której została wykonana, w przeciwnym razie komunikat zatwierdzenia pokazuje po prostu coś w rodzaju „scalony z gałęzi Y”. Gałąź Y może pokazywać „scalony z gałęzi Z”, a gałąź kilka poziomów zagnieżdżenia głębszego faktycznie ma prawdziwy komunikat zatwierdzenia.

Nowy pracownik nie wiedział, jak prawidłowo wyśledzić historię, co oznacza, że ​​zasadniczo pracował tylko z różnicami. Zobaczył skomentowany kod związany z błędem, który śledził. Kiedy odkomentował kod, jego błąd zniknął. Zakładał, że ktoś skomentował kod podczas debugowania i przez pomyłkę go sprawdził.

To nie wydawało się słuszne dla niektórych z nas podczas sprawdzania kodu, więc wyśledziłem prawdziwy komunikat zatwierdzenia i odkryłem, że istnieje uzasadniony powód, aby usunąć ten kod rok temu. Nowy pracownik był w stanie naprawić swój kod, aby naprawić nowo wykryty błąd bez ponownego wprowadzania starego.

Są lepsze sposoby, aby uniknąć wprowadzania tego rodzaju regresji, takie jak dokładne testy jednostkowe, ale jakoś nie widzę ludzi, którzy nie mogą zawracać sobie głowy 2-sekundowym komunikatem „marnowania” czasu na testowanie jednostkowe.

Miałem tutaj dokładnie ten sam problem, więc dodałem haczyk przed zatwierdzeniem do Subversion, aby nie akceptował żadnych zatwierdzeń, które nie zaczynały się od numeru Story użytkownika (niektóre podstawowe dopasowanie wzorca dla oczekiwanego formatu).

Nic nie powstrzymuje ich przed wejściem na 000-0000, ale kiedy tylko destrukcyjny idiota nadrobi liczbę, gdy będzie tam całkowicie akceptowalna liczba.

Zrobiłem to po spędzeniu dni, próbując znaleźć, w jaki sposób buduje zestaw historii użytkowników. Tak, miało to miejsce w przypadku awarii procesu, ale nadal jest to niezwykle cenna informacja do śledzenia.

Dobre komentarze zatwierdzające są jak każda dobra dokumentacja, pamięć podręczna dla powolnego i nieczynnego mózgu lub pamięć podręczna wyników wszelkich długich debugowania / analizy / badania problemu.

Na przykład za każdym razem, gdy spędzasz czas na rozwiązywaniu problemów, takich jak debugowanie, analiza dzienników lub cokolwiek innego, twoje wyniki i wyniki są cenne. Oczywiście większość zadań można powtórzyć, ale może to zająć trochę czasu. Dlatego zawsze powinieneś dokumentować swoje wyniki.

Dokumentacja wymaga jednak czasu i czasami wydaje się, że nie jest konieczna, na przykład „musieliśmy to zrobić tylko raz, więc po co to zapisywać”. To w porządku, ale jak tylko zrobisz to samo po raz drugi, ponieważ nie udokumentowałeś wyników za pierwszym razem, to oczywiście sprytnie jest udokumentować wyniki.

Więc jeśli Twoi koledzy uważają, że dodawanie komentarzy jest zbyt pracochłonne, np. Przynajmniej wskazują na sprawę Jira / Bilet, którą rozwiązywali, to może motywować ich presja ciągłego odpowiadania na pytania dotyczące przyczyny każdego z nich zestaw zmian.

Moim zdaniem dokumentację należy opracować jako funkcję żądanej informacji. Na przykład korespondencja pocztowa jest całkiem dobrym systemem dokumentacji. Pytania otrzymują odpowiedzi, które można później odzyskać, w ten sposób listy mailingowe i fora działają w praktyce jako bazy wiedzy.

Niestety tam, gdzie pracuję, poczta jest automatycznie usuwana po 3 miesiącach, więc nie zawsze działa w praktyce.

Szukajcie przebaczenia, a nie pozwolenia.

Chociaż byłem surowy, właśnie to zrobiłem. Miałem podział 50/50 między osobami wspierającymi i przeciwnymi, z których większość była na tym samym poziomie co ja w grupie. Argumenty brzmiały: „Nie przejmuję się” i „O co chodzi?”. (Oba wskazują na apatię i lenistwo, a nie prawdziwe obawy).

Dodałem hak przed zatwierdzeniem, który po prostu mierzył długość struny i dał nieco humorystyczny komunikat, zanim go odrzuciłem. Umieściłem swoje imię w wiadomości, więc odpowiedzialność za „to oburzenie” była jasna. Oczywiście „opozycja” mogłaby go łatwo usunąć, ale wkopanie się w skrypty wymagałoby więcej wysiłku niż dodanie jeszcze jednego komentarza!

Przez tydzień otrzymywałem wiadomości takie jak * * (przekreślone usunięte) lub kjhfkwhkfjhw. Następnie zaczęły pojawiać się podstawowe wiadomości.

Rok później sceptycy używają znaczących komentarzy i przyznają, że byli krótkowzroczni. Nigdy nie mogłem osiągnąć konsensusu, ale z pewnością dostałem przebaczenie i być może wiarygodność. Działa, ludzie go używają.

Jeśli chcesz być bardziej sympatyczny (lub czujesz, że będziesz miał kłopoty), poproś o pozwolenie na dodanie haka zatwierdzającego na okres próbny. Powiedz, że jeśli ludziom się to nie spodoba za 2 tygodnie lub 4 tygodnie, wyjmiesz to. Są szanse, że stracą zainteresowanie ... lub polubią to.

Zazwyczaj przekonuję ludzi poprzez:

• dialektyka z uzasadnionymi przyczynami
• prowadząc przez przykład
• ścieranie

Gdybym chciał, aby nasz zespół zrobił coś wystarczająco złego, wciąż bym się starał, dopóki nie dojdę do siebie. Staram się męczyć w czasach, w których mogę zauważyć, że moglibyśmy zaoszczędzić czas / pieniądze, gdybyśmy już robili X.

Dodatkowe powody, dla których warto zatwierdzać komentarze:

• Automatyczne generowanie ChangeLog na podstawie komentarzy.
• Ścieżka audytu poprawek błędów, dodatków do funkcji. Jest to przydatne zarówno w zespole, jak i poza nim.
• Uczyń pocztę zatwierdzania bardziej przydatną.
• Powstrzymaj mnie przed pytaniem programisty, co robi X (po prawie każdym zatwierdzeniu).

• Sprawdź, czy w dziennikach SVN nie znaleziono czegoś ukrytego wykonanego 6 miesięcy temu.
• Zadaj kilka pytań na ten temat, nie mówiąc, kiedy to zostało zrobione
• ???
• Zysk

Jak sprawić, by chcieli dodawać dobre komentarze?

Z doświadczenia, które właśnie miałem. Pod koniec projektu musieliśmy napisać dokument podsumowujący wszystkie zmiany dokonane w całym projekcie. Nie robiąc dobrych notatek z zatwierdzeniami, mój kolega uznał to zadanie za czasochłonne, i teraz zaczął robić dość długie komentarze przy każdym zatwierdzeniu.

Tak więc - na wynos - jednym z rozwiązań mogłoby być poproszenie programistów o napisanie na końcu projektu dokumentów podsumowujących szczegółowo, jakie zmiany zostały wprowadzone w jakich plikach, jakie pliki zostały dodane / usunięte i dlaczego.

Zaproponuj to zarządowi za zamkniętymi drzwiami:

Najgorszy scenariusz ma miejsce: wszyscy programiści z wyższego poziomu wychodzą za drzwi.

Gdy firma stara się zapełnić puste stanowiska programistów, zespół zarządzający ma za zadanie przekazać klientowi informacje o stanie systemu.

Zapytaj ich, co według nich ułatwiłoby ich pracę przy rekonstrukcji historii aplikacji:

Czytanie zwykłych angielskich poleceń, które jasno opisują zmieniający się stan systemu?

Czy woleliby przyjrzeć się różnicom w kodzie i sami to odkryć?

Sądzę, że jednym ze sposobów na przekonanie ich byłoby faktyczne odczuwanie bólu, który odczuwasz.

Załóżmy na przykład, że pracują nad następującym problemem: Mają błąd, który w jakiś sposób pojawił się, gdy zaimplementowano kolejną naprawę błędu dla tego samego kodu (o ironio). Byłoby wspaniale móc to sprawdzić po przeszukaniu komunikatów zatwierdzenia (i tym samym dowiedzieć się, kto to napisał).

Innym sposobem byłoby wyjaśnienie im, że komunikat zatwierdzenia może być przydatny, aby dać wskazówkę, dlaczego coś zostało zaimplementowane w określony sposób. Nawet jeśli komunikat zatwierdzenia mówi po prostu „funkcja X”, nadal możesz uzyskać wskazówkę, kto go zaimplementował, abyś wiedział, z kim porozmawiać.

Nie wydaje się to jednak wystarczające, aby zwalczyć dwie odpowiedzi, które zawsze otrzymuję:

1. Trwa to zbyt długo i chcę tylko wprowadzić zmiany w repozytorium.
2. Wystarczy spojrzeć na różnice.

Czy próbowałeś rzucić wyzwanie innym programistom, aby mieli oni inne korzyści z dodawania komentarzy? Można na to spojrzeć z kilku różnych punktów widzenia:

1. Wzmocnienie gry - może to być trudniejsza perspektywa, ale tutaj chodzi o to, że robią to przez pewien czas i przyzwyczajają się do pomysłu, aby nawyk był dłuższy. Kolejną kwestią jest to, ile kontroli otrzymają komentarze? Jeśli chcesz krótkiej historii w komentarzu, rozumiem ich sens.
2. Subsydiowanie zmiany - w tym miejscu możesz wziąć udział w jakimś konkursie, aby uzyskać wstępne wpisowe w celu wypróbowania tego lub zaoferować inny rodzaj zachęty do wprowadzenia zmiany na jakiś czas.

Inną kwestią do rozważenia jest to, jak dobrze wiesz, czym zarządzają Twoi inni programiści w miejscu pracy? Jeśli próbują wczoraj zrobić 10 rzeczy, rozumiem, że mogą nie chcieć zmieniać tego, co postrzegają jako coś, co już działa. Próbujesz im powiedzieć: „Nie, to nie działa?” Jeśli tak, to widzę, jak mogą być w tym nieco defensywni lub bojowi. Jeśli próbujesz im powiedzieć: „Chociaż to może zadziałać, istnieje alternatywa, która może być lepsza ...”, możesz mieć szansę. Posiadanie podejścia „bardziej świętego niż ty” nie pomoże ci, IMO.

Innym sposobem patrzenia na to jako sposób na dewelopera (ów) zaangażowanych rozwijać swoje kariery - powinni właścicielem w dokumentacji ich pracy.

Oprócz innych kwestii poruszonych w wyżej wspomnianym artykule istnieje możliwość przejrzenia zmian w kodzie, aby dowiedzieć się, gdzie / kiedy / dlaczego dokonano zmiany. Może to być niezbędne przy śledzeniu nieuchwytnego błędu.

Po przekonaniu ich, że ważne jest komentowanie swoich zatwierdzeń, możesz utworzyć skrypt, który wymusza komentarze na zatwierdzeniach, w przeciwnym razie się nie powiedzie. Możesz nawet określić minimalną liczbę znaków, aby zapewnić znaczący komentarz. Pomoże im to „zapamiętać”.

Ważne jest jednak, aby rozumieli Dlaczego, jak powiedział @Kevin, w przeciwnym razie dodadzą dowolny przypadkowy komentarz.

Czy masz recenzje kodu? Jedną z rzeczy, które mogą pomóc, jest ustanowienie reguły, zgodnie z którą każde zatwierdzenie lub scalenie musi być sprawdzone i zatwierdzone przez innego programistę. Następnie, jeśli jesteś recenzentem, musisz poprosić programistę, który zobowiązuje się do wyjaśnienia, co zrobił. Kiedy to zrobi, powinieneś poprosić go o wpisanie w komentarzu tego, co właśnie powiedział. Często, gdy nie można w spójny sposób wyjaśnić dokonanych zmian, oznacza to, że zmiany te nie powinny były zostać wprowadzone.

Muszę jednak powiedzieć, w jaki sposób ludzie mogą sprzeciwić się tak oczywistemu pożytecznemu komentarzowi? To wcale nie trwa długo i jest to czas dobrze spędzony. Napisanie komentarza zmusza do myślenia o tym, co właśnie zrobiłeś. Może nawet sprawi, że spojrzysz na różnice, aby upewnić się, że rzeczywiście zrobiłeś to, co według ciebie zrobiłeś, i że nie zrobiłeś nic głupiego.

Kiedy nie piszesz komentarzy, jesteś niechlujny i niezdyscyplinowany. A jeśli nalegasz, abyś nie był zobowiązany do pisania komentarzy, to umyślnie zaniedbujesz.

Powiedz im, że jest to jedyny sposób, aby mieć szansę na utrzymanie bałaganu proceduralnego przy użyciu 50 000 metod liniowych, a następnie zastanów się nad lepszym, bardziej wyraźnym kodem w przyszłości, abyś nie musiał radzić sobie z mnóstwem bezsensownych komentarzy obarczających bazę kodu.

Jest to element zmiany procesu: Poproś kierownika o przypisanie kodu opracowanego przez „x” do „Y” w celu kontroli jakości samego kodu, w tym kontroli jakości komentarzy.

W mojej organizacji programiści nie mogą przeprowadzać ostatecznej kontroli jakości własnego kodu i rejestrować go, musi to zrobić inny programista. Częścią kontroli jakości są komentarze, więc bez komentarzy, bez odprawy. Wykonujemy wiele prac kontraktowych, w których nasza „sztuka” jest faktycznie umowną własnością intelektualną innej osoby, więc inni muszą być w stanie zrozumieć i wykorzystać nasz kod. Są też chwile, kiedy projekty wracają do nas po długiej przerwie i musimy być w stanie odebrać kod 18–24 miesięcy później i zrozumieć, dlaczego, gdzie i jak dotarliśmy do artefaktu kodu przed nami. Zapewnia to samoobsługową motywację do pisania komentarzy do zatwierdzenia.

Poproś innych programistów, aby przeprowadzili fuzje i przeszukali historię oraz porównali kilka plików z historii.

Są szanse, że poproszą cię o komentarze na następny dzień.

Oto kilka porad:

1. Nie próbuj zmieniać świata. Nie zdasz.
2. Zamiast tego powinieneś zauważyć, że każdy działa nieco inaczej. Żaden rozmiar nie pasuje do wszystkich.
3. wymaganie określonych kroków w procesach pracy ludzi jest bardzo złe. Zmiana tych procesów zajmuje 10 lat. Poprosisz ich o zrobienie tego przed następnym terminem.
4. Nawet proste zmiany procesu mogą zająć dużo czasu.
5. Mały komentarz do zatwierdzeń jest zbyt mało znaczący, aby zmienić te procesy.
6. Możesz założyć, że wykonują dobrą pracę, ale powinny dać wystarczającą swobodę w samodzielnym wyborze kroków. Doświadczeni programiści mogą nie wymagać pewnych uciążliwych kroków.
7. Jeśli opiekujesz się nowicjuszami, konieczne mogą być silniejsze procesy, ale doświadczeni programiści nie powinni zajmować się bzdurami.
8. Nakładanie drakońskich ograniczeń dotyczących sposobu wykonywania pracy nigdy nie będzie działać, może jedynie spowolnić ludzi (może być dobre, jeśli są zbyt szybkie)
9. Jest wielu ludzi, którzy myślą, że ich sposób jest jedynym właściwym sposobem robienia rzeczy. Mam nadzieję, że nie jesteś jednym z nich.

Jeśli kontrola źródła to udowodni, włącz obowiązkowe komentarze, aby uniknąć niepomentowanych poleceń. To proste, a wszyscy wkrótce zrozumieją, że 5 sekund wpisywania komentarza jest bezbolesne.

Ale niezakomentowane zmiany są jednym z najmniejszych negatywów. Brałem udział w wielu udanych projektach, w których nie komentowano ani jednego zatwierdzenia. Nie wkładaj w to majtek.