Jak poradzić sobie z członkiem zespołu, który nie lubi komentować kodu?

Jeden z członków mojego zespołu konsekwentnie unika komentowania swojego kodu.

Jego kod nie dokumentuje się sam, a inni programiści mają trudności ze zrozumieniem jego kodu.

Kilkakrotnie prosiłem go o skomentowanie jego kodu, jednak on tylko usprawiedliwia lub twierdzi, że zrobi to później. Martwi go, że dodawanie komentarzy zajmie zbyt dużo czasu i opóźni projekty.

Jaki argument mogę mu przedstawić, aby przekonać go do prawidłowego udokumentowania swojego kodu?

Czy w tej notatce mylę się skupiając na komentarzach do kodu, czy też wskazuje to na większy problem, który należy rozwiązać?

Same komentarze nie stanowią lepszego kodu, a naciskanie na „więcej komentarzy” może dać ci niewiele więcej niż /* increment i by 1 */komentarze w stylu.

Więc zadaj sobie pytanie, dlaczego chcesz te komentarze. „To najlepsza praktyka” nie liczy się jako argument, chyba że rozumiesz dlaczego.

Teraz najbardziej uderzającym powodem używania komentarzy jest to, że kod jest łatwiejszy do zrozumienia, a kiedy ludzie narzekają na brak komentarzy, są albo nieświadomymi papugami, albo mają trudności ze zrozumieniem kodu, z którym pracują.

Więc nie narzekaj na brakujące komentarze: narzekaj na nieczytelny kod. Albo jeszcze lepiej, nie narzekaj, po prostu zadawaj pytania dotyczące kodu. O cokolwiek, czego nie rozumiesz, zapytaj osobę, która to napisała. I tak powinieneś to robić; z nieczytelnym kodem, po prostu zadajesz więcej pytań. A jeśli wrócisz do fragmentu kodu później i nie masz pewności, czy dobrze pamiętasz, co on robi, ponownie zadaj to samo pytanie.

Jeśli komentarze mogą to naprawić, a twój kolega ma sprawny mózg, w pewnym momencie zda sobie sprawę, że komentowanie kodu jest znacznie łatwiejsze niż ciągłe zadawanie głupich pytań. A jeśli nie możesz wymyślić pytań, być może ten kod jest już doskonale czytelny i to ty jesteś winien - w końcu nie cały kod wymaga komentarza.

Jeśli chodzi o umiejętności ludzi, unikaj brzmiąc protekcjonalnie lub oskarżając za wszelką cenę; mów poważnie i szczerze.

Spotkałem wielu deweloperów, którzy mieli problemy z pisaniem samodokumentującego się kodu lub pomocnymi komentarzami. Tacy ludzie często nie mają wystarczającej samodyscypliny lub doświadczenia, aby zrobić to dobrze.

To, co nigdy nie działa, to „każenie im dodawać więcej komentarzy”. Nie zwiększy to ich samodyscypliny ani doświadczenia. IMHO jedyne, co może zadziałać, to częste przeglądy kodu i sesje refaktoryzacji. Gdy programista wykona zadanie, pozwól mu wyjaśnić wszystkie części kodu, których nie rozumiesz. Natychmiast prześlij kod lub udokumentuj kod w taki sposób, abyś zrozumiał 6 miesięcy później.

Rób to przez kilka miesięcy, przynajmniej dwa razy w tygodniu. Jeśli masz szczęście, inni deweloperzy nauczą się podczas tych sesji, abyś mógł zmniejszyć częstotliwość recenzji.

Dziwi mnie, że nikt jeszcze nie wspomniał o recenzjach kodu. Czy recenzje kodu! Kiedy ma odprawę złej jakości, nie mów tylko „dodaj komentarze”. Ciągle zadawaj pytania i każ mu powiedzieć, co robi jego kod i dlaczego. Robić notatki. Następnie na końcu przeglądu kodu daj mu kopię notatek i powiedz mu, aby zadał ci dość oczywiste pytania. Albo przez więcej komentarzy, albo przez przeredagowanie kodu, aby poprawić jego jakość (najlepiej ten drugi, jeśli to możliwe)

Zależy to od kodu tworzonego przez pracownika zespołu. Jeśli przeczytasz książkę „ Czysty kod ” wuja Boba, przekonasz się, że tak naprawdę nie chce dodawać komentarzy do kodu. Jeśli sam kod jest tak czytelny, jak powinien, to prawie nie ma potrzeby komentowania.

Jeśli tak nie jest lub potrzebujesz komentarzy z powodu jakiejś niezbywalnej polityki, wówczas główne pytanie brzmi, czy tylko Ty chcesz , aby on / ona napisała komentarze, czy też jest to cały zespół, czy zespół / projekt. lider. Jeśli to tylko ty, powinieneś porozmawiać z innymi kolegami, aby dowiedzieć się, dlaczego wcale nie jest to taka wielka sprawa.

Jeśli lider projektu nie ma komentarzy, możesz również wymagać ich jako części kompletności , tj. Jeśli przesłany kod nie zawiera komentarza, praca nie jest jeszcze ukończona. Nie może kontynuować wykonywania innej pracy, dopóki jego obecna praca nie zostanie zakończona i do tego są wymagane komentarze. Należy jednak pamiętać, że tego rodzaju wymuszanie najprawdopodobniej spowoduje okropne komentarze (spodziewaj się mnóstwa gównianych powtórzeń kodu).

Moim skromnym zdaniem jedynym wykonalnym sposobem jest omówienie faktycznych zysków, jakie ty i wszyscy inni otrzymacie z komentarzy. Jeśli nie rozumie go przez samą dyskusję, zawsze jest też trudna droga: zamiast pozwolić im napisać nowy kod, niech pracują na istniejącym kodzie. Jeśli to możliwe, powinieneś znaleźć dla nich dwa różne obszary robocze - jeden z odpowiednimi przydatnymi komentarzami, a drugi bez komentarzy. Konieczność przeczytania nieczytelnego kodu, który nie został skomentowany, jest nieocenionym rozwiązaniem w odniesieniu do własnej pracy.

Wszyscy byliśmy tam raz i byliśmy źli na oryginalnego autora jakiegoś źródła za pracę tak niechlujną. Jest to dodatkowa refleksja, że ​​każdy z nas jest również autorem, który uświadamia, że ​​powinieneś dbać o czytelność - dlatego nie zapomnij omówić wyników z kolegą później, aby promować tę refleksję.

Jeśli masz pracownika, który nie potrafi postępować zgodnie z instrukcjami, napomnij go i upewnij się, że nie pomoże to w rozwoju kariery. Konsekwencja w stylu kodowania ma kluczowe znaczenie dla zespołu, a jeśli wszyscy inni piszą komentarze, a ten nie jest, szkodzi to stylowi kodowania.

To powiedziawszy, prawdopodobnie możesz mu pomóc. Z mojego doświadczenia wynika, że ​​gdy ktoś protestuje, że komentowanie zajmuje zbyt dużo czasu, istnieje bariera psychologiczna, taka jak…

1. Jest samoświadomy swoich wyborów dotyczących kodu / projektu i nie chce przedstawiać ich w prozie. (Przeglądy kodu mogą być pomocne w zwiększaniu czyjejś pewności siebie, a także w niszczeniu ich).
2. Pracuje bardzo liniowo i niewiele myśli. Komentowanie jest bolesne, ponieważ zmusza go do zwolnienia natychmiastowego kodu, który zamierzał napisać ze swojej pamięci roboczej, w celu skomponowania zamiaru w inny sposób. (Jeśli to prawda, komentowanie staje się bardzo ważne dla jego jakości kodu).
3. Historycznie ludzie nie rozumieją jego komentarzy.

Ważne jest, aby programiści zdali sobie sprawę, że komentarze są jak testy: nie są one tylko do wykorzystania w przyszłości - są one dla samego programisty. Zmuszają go do odmiennego myślenia o swoim podejściu.

Nic z tego nie zastępuje CI, testów ani recenzji kodu. To tylko jedna z wielu krytycznych części kodowania, która sama w sobie nie polega na pisaniu kodu.

Pobierz oprogramowanie do przeglądania kodu i używaj go dobrze.

Używamy pieca i uwielbiamy to. Mamy zasadę, że każdy zestaw zmian musi zostać przejrzany (chociaż zezwalamy deweloperom na podnoszenie / zatwierdzanie recenzji dla tagów i połączeń bez konfliktów (chociaż większość z nas korzysta z rebaseif); w ten sposób możemy szybko wykryć zestawy zmian bez recenzji).

Niepewny kod jest przyczyną odrzucenia recenzji kodu. Nie ma znaczenia, czy poprawką są komentarze czy wyraźniejszy kod, ale recenzent musi być w stanie to zrozumieć. Niektórzy deweloperzy wolą przepisać kod, ale innym (łącznie ze mną) często łatwiej jest wyrazić intencję w komentarzach (kod może łatwo pokazać, co robi, ale trudniej jest pokazać, co powinien zrobić).

Jeśli kiedykolwiek pojawi się pytanie o przejrzystość kodu, recenzent zawsze wygrywa. Oczywiście autor to rozumie, ponieważ to napisał. To musi być jasne dla innej osoby.

Używając oprogramowania takiego jak Kiln, żaden zestaw zmian nie zostaje przeoczony. Wszyscy w moim zespole deweloperów wolą to w ten sposób. Oprogramowanie do przeglądu kodu miało ogromny wpływ zarówno na jakość naszego kodu, jak i jakość aplikacji :-)

Deweloperzy mogą łatwo obronić się dzięki odrzuconym recenzjom podczas pierwszego wprowadzenia oprogramowania, ale z mojego doświadczenia wynika, że ​​nie trzeba długo czekać, aby zrozumieć, że w ten sposób jest lepiej i przyjąć to :-)

Edycja: Warto również zauważyć, że staramy się, aby deweloperzy nie wyjaśniali tajemniczego kodu słownie lub w komentarzach w recenzji. Jeśli coś nie jest jasne, najlepszym miejscem na wyjaśnienie tego jest kod (w komentarzach lub przez refaktoryzację), a następnie dodaj nowe zestawy zmian do tej samej recenzji.

Interesujące jest to, że czytelność w odniesieniu do języka naturalnego mierzy się szybkością czytania i rozumienia. Wydaje mi się, że rzeczywiście można zastosować prostą regułę, jeśli określony komentarz kodu nie poprawi tej właściwości, można tego uniknąć .

Dlaczego komentarze

Chociaż komentarz do kodu jest formą osadzonej dokumentacji, w zaawansowanych językach programowania istnieje wiele sposobów na uniknięcie zbędnego „nadmiernie udokumentowanego” programowania (znaczącego kodu) przy użyciu elementów samego języka. Niewłaściwym pomysłem jest również przekształcenie kodu w zestawienia z podręcznika programowania, w którym poszczególne stwierdzenia są dosłownie wyjaśnione niemal w sposób tautologiczny (pamiętaj przykład „/ * przyrost i o 1 * /” w już dostarczonych odpowiedziach), dzięki czemu takie komentarze są istotne tylko dla programistów niedoświadczonych w języku.

Niemniej jednak intencją jest skomentowanie „niedokumentowanego” (ale bez znaczenia) kodu, który jest naprawdę „źródłem wszelkiego zła”. Samo istnienie „nieudokumentowanego” kodu jest złym sygnałem - albo jest to nieuporządkowany bałagan, albo zwariowany hack mistycznego utraconego celu. Oczywiście wartość takiego kodu jest co najmniej wątpliwa. Niestety zawsze istnieją przykłady, kiedy rzeczywiście lepiej jest wprowadzić komentarz do sekcji (wizualnie zgrupowanych) sformatowanych wierszy kodu niż zawinąć go w nowy podprogram (pamiętaj o „głupiej konsystencji”, która „jest hobgoblinem małych umysłów”) .

Czytelność kodu! = Komentarze do kodu

Czytelny kod nie wymaga adnotacji w komentarzach. W każdym konkretnym miejscu kodu zawsze znajduje się kontekst zadania, które ten konkretny kod ma wykonać. Jeśli brakuje celu i / lub kod robi coś tajemniczego = unikaj go za wszelką cenę. Nie pozwól, aby dziwne włamania wypełniły Twój kod - jest to bezpośredni wynik połączenia wadliwych technologii z brakiem czasu / zainteresowania, aby zrozumieć podstawy. Unikaj mistycznego kodu w swoim projekcie!

Z drugiej strony, Czytelny program = kod + dokumentacja może zawierać wiele uzasadnionych sekcji komentarzy, np. W celu ułatwienia generowania dokumentacji „komentarze do API”.

Przestrzegaj standardów stylu kodu

Zabawne jest to, że nie chodzi o to, dlaczego komentować kod, chodzi o pracę zespołową - jak tworzyć kod w wysoce zsynchronizowanym stylu (który wszyscy inni mogą czytać / rozumieć). Czy przestrzegasz w swojej firmie standardów stylu kodu? Jego głównym celem jest unikanie pisania kodu, który wymaga refaktoryzacji, jest zbyt „osobisty” i „subiektywnie” dwuznaczny. Sądzę więc, że jeśli dostrzeże się konieczność korzystania ze stylu kodu, istnieje cały szereg narzędzi, jak poprawnie go zaimplementować - zaczynając od edukacji ludzi, a kończąc na automatyzacji kontroli jakości kodu (liczne wskazówki itp.) I (rewizja) zintegrowane systemy kontroli).

Zostań ewangelistą czytelności kodu

Jeśli zgadzasz się, że kod jest czytany częściej niż jest zapisywany. Jeśli jasne wyrażenie idei i jasne myślenie jest dla Ciebie ważne, bez względu na to, jaki język jest używany do komunikacji (matematyka, kod maszynowy lub staroangielski) .. Jeśli Twoim zadaniem jest wyeliminowanie nudnego i brzydkiego sposobu alternatywnego myślenia ... (przepraszam , ostatni pochodzi z innego „manifestu”) .. zadawaj pytania, inicjuj dyskusje, zacznij rozpowszechniać prowokujące do myślenia książki na temat czyszczenia kodu (prawdopodobnie nie tylko coś podobnego do wzorców projektowych Becka, ale bardziej podobne do wspomnianych już przez RC Martina ), które odnoszą się do dwuznaczności w programowaniu. Dalej znajduje się punktator kluczowych pomysłów (cytowany z książki O'Reilly o czytelności)

• Uprość nazywanie, komentowanie i formatowanie dzięki poradom, które dotyczą każdego wiersza kodu
• Udoskonal pętle, logikę i zmienne programu, aby zmniejszyć złożoność i zamieszanie
• Problemy z atakiem na poziomie funkcji, takie jak reorganizacja bloków kodu w celu wykonania jednego zadania na raz
• Napisz skuteczny, dokładny i zwięzły kod testowy, a także czytelny

Wycinanie „komentowania” pozostawia wiele do zrobienia ( wydaje mi się, że pisanie kodu, który nie wymaga komentarzy, jest świetnym ćwiczeniem!). Nazywanie semantycznie znaczących identyfikatorów to dobry początek. Następnie ustrukturyzuj swój kod, grupując logicznie połączone operacje w funkcje i klasy. I tak dalej. Lepszy programista to lepszy pisarz (oczywiście przy założeniu innych umiejętności technicznych).

czy mylę się skupiając na komentarzach do kodu, czy też wskazuje to na większy problem, który należy rozwiązać?

Nieco. Świetny kod nie potrzebuje komentarzy. Jednak, jak powiedziałeś, jego kod nie jest samodokumentujący. Nie skupiałbym się więc na komentarzach. Powinieneś skupić się na doskonaleniu umiejętności i kunsztu swoich programistów.

Jak to zrobić? Sugestie doktora Browna dotyczące recenzji / sesji refaktoryzacyjnych to dobry pomysł. Uważam, że programowanie w parach jest jeszcze bardziej skuteczne, ale może być znacznie trudniejsze do wdrożenia.

Przede wszystkim proponuję, abyś zmienił swoje podejście do komentarzy.

Jeśli są to komentarze do dokumentacji na poziomie API (później ujawnione publicznie), to ten programista po prostu nie wykonuje swojej pracy. Ale zachowaj ostrożność przy wszystkich innych komentarzach.

W większości przypadków, z którymi się spotykam, komentarze są złe. Poleciłbym przeczytać rozdział o komentarzach do kodu w „Czystym kodzie” Roberta Martina, aby dobrze zrozumieć, dlaczego.

Komentarze szkodzą Twojemu kodowi na kilka sposobów:

1) Są trudne do utrzymania. Podczas refaktoryzacji będziesz musiał włożyć dodatkową pracę; jeśli zmienisz logikę opisaną w komentarzu, musisz również edytować komentarz.

2) Często kłamią. Nie możesz ufać komentarzom i zamiast tego musisz przeczytać kod. Co nasuwa pytanie: dlaczego w ogóle potrzebujesz komentarzy?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(Hash nie jest sumą, ale produktem).

3) Komentarze zaśmiecają kod i bardzo rzadko dodają żadnej wartości.

Moje rozwiązanie: Zamiast dodawać więcej komentarzy, spróbuj ich w ogóle pozbyć!

Jeśli członek zespołu ma problemy ze zrozumieniem kodu innego członka zespołu (z dowolnego powodu); wtedy ten członek zespołu powinien być w stanie dowiedzieć się, kto napisał oryginalny kod (każdy rozsądny system kontroli wersji) i powinien zostać zachęcony, aby autor kodu wyjaśnił go bezpośrednio (np. podszedł do swojego biurka, usiadł i omówił go).

W takim przypadku, jeśli brak komentarzy stanowi problem, osoba, która nie komentuje odpowiednio swojego kodu, poświęci dużo czasu na wyjaśnienie tego, co zrobiła; i (jeśli są mądrzy) zaczną dodawać komentarze, aby uniknąć poświęcania czasu na wszystkie te wyjaśnienia.

Pamiętaj, że zachęcanie członków zespołu do wzajemnego zadawania pytań jest cenne z innych powodów. Na przykład członek zespołu może być mniej doświadczony i może uczyć się od bardziej doświadczonych członków zespołu.

Przeważnie zachęcając członków zespołu do wzajemnych zapytań o wyjaśnienia, tworzysz system samowyważenia; gdzie różni członkowie zespołu „dostosowują się” do siebie.

Jest to w dużej mierze rozszerzenie odpowiedzi tdammerów, ale przeglądaj kod w regularnych odstępach czasu.

Posiadanie go (i innych programistów), siadania, przeglądania kodu i mniej więcej obrony przed przełożonymi i rówieśnikami sprawi, że wszyscy będą lepszymi programistami i dodadzą prawdziwą wartość w stosunkowo krótkim czasie. W krótkim okresie nie da to deweloperowi żadnego usprawiedliwienia, aby w momencie przeglądu odpowiednio skomentować swój kod.

EDYCJA: Nie jestem pewien, dlaczego ktoś odmówiłby mojej sugestii - być może uznałem za pewnik, że korzyści z przeglądu kodu byłyby powszechnie znane ... zobacz ten wątek na temat analizy społeczności dotyczącej tej praktyki:

Czy przegląd kodu jest dobrą praktyką?

Biorąc pod uwagę często skrajne poglądy na komentowanie, waham się nad tym. Zastanawiam się nad tym ...

Jakie są niektóre argumenty, które mogę przedstawić, aby napisać (nieczytelny) kod, który powinien być odpowiednio udokumentowany?

Zrozumienie sposobu pisania łatwego do utrzymania i czytelnego kodu wymaga czasu, praktyki i doświadczenia. Niedoświadczeni programiści (i niestety wielu doświadczonych) często cierpią na efekt Ikea ( PDF ). To dlatego, że go zbudowali i są z nim ściśle zaznajomieni, i są pewni, że kod jest nie tylko świetny, ale także czytelny.

Jeśli osoba jest świetnym programistą, to niewiele, jeśli wymagana jest dokumentacja. Jednak większość programistów nie jest świetna i wiele kodu ucierpi w dziale „readablity”. Poproszenie przeciętnego lub programisty o „wyjaśnienie swojego kodu” jest przydatne, ponieważ zmusza ich do oglądania kodu bardziej krytycznym okiem.

Czy to oznacza „dokumentowanie” ich kodu? Niekoniecznie. W tym przypadku miałem w przeszłości podobnego programistę z tym problemem. Zmusiłem go do udokumentowania. Niestety jego dokumentacja była tak samo nieczytelna jak jego kod i nic nie dodała. W kodzie retrospektywnym recenzje byłyby bardziej pomocne.

Ty (lub delegat) powinieneś usiąść z tym programistą i wyciągnąć trochę jego starszego kodu. Nie nowe rzeczy, które zna po prostu nad tym popracować. Powinieneś poprosić go, aby przeprowadził cię przez jego kod przy minimalnej interakcji. Może to być także osobna sesja „dokumentowania”, w której ma wyjaśnić na piśmie swój kod. Następnie powinien uzyskać informację zwrotną na temat lepszego podejścia.

Na marginesie ... czasami potrzebna jest pewna dokumentacja, niezależnie od tego, jak dobra jest „czytelność” kodu. Interfejsy API powinny mieć dokumentację, niezwykle techniczne i złożone operacje powinny mieć dokumentację, aby pomóc programistom w zrozumieniu zaangażowanych procesów (często poza domeną wiedzy programistów), a niektóre rzeczy, takie jak złożone wyrażenia regularne, powinny naprawdę udokumentować to, do czego pasujesz.

Wiele projektów wymaga dokumentacji kodu: dokument interfejsu, dokument projektowy, ...

Niektóre projekty wymagają, aby taka dokumentacja była umieszczana w komentarzach do kodu i wyodrębniana za pomocą narzędzi takich jak Doxygen, Sphinx lub Javadoc, aby kod i dokumentacja były bardziej spójne.

W ten sposób programiści są zobowiązani do pisania użytecznych komentarzy w kodzie, a obowiązek ten jest zintegrowany z planowaniem projektu.

Przedstawię, na co wskazuje większość odpowiedzi i komentarzy: prawdopodobnie musisz tutaj znaleźć prawdziwy problem, zamiast próbować przeforsować swoje postrzegane rozwiązanie.

Masz motywację, aby zobaczyć komentarze w jego kodzie; dlaczego ? Podałeś powód; dlaczego ten powód jest dla ciebie taki ważny? Jest bardziej zmotywowany do zrobienia czegoś innego; dlaczego ? Poda powód; dlaczego ten powód jest dla niego tak ważny? Powtarzaj to, aż dojdziesz do poziomu, na którym naprawdę powstaje konflikt, i spróbuj znaleźć rozwiązanie, z którym oboje możecie żyć. Założę się, że ma to bardzo niewiele wspólnego z komentowaniem.

Jeśli będziesz przestrzegać dobrego standardu kodowania, wymagana będzie minimalna liczba komentarzy. konwencje nazewnictwa są ważne. Nazwy metod i nazwy zmiennych powinny opisywać ich rolę.

Moja TL sugeruje, żebym używał mniej komentarzy. chce, żeby mój kod był zrozumiały i opisowy. prosty przykład: nazwa zmiennej dla typu ciągu używanego do wzorca wyszukiwania

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Uwielbiam odpowiedzi na recenzje kodu, ale być może mój proces też trochę pomoże.

Uwielbiam komentarze, ale prawie nigdy nie dodam ich do kodu przy pierwszym przejściu. Może to tylko mój styl, ale w trakcie programowania uderzę w tę samą sekcję kodu 3 do 5 razy (refaktoryzacja, pisanie testów itp.).

Ilekroć jestem trochę zdezorientowany lub gdy ktoś zadaje mi pytanie dotyczące fragmentu kodu, próbuję go naprawić, aby miał sens.

Może to być tak proste, jak dodanie komentarza usuwającego mylący zestaw operacji do ich własnych funkcji lub może wywołać większy refaktor, taki jak wyodrębnienie nowego obiektu.

Sugeruję, aby zachęcić wszystkich członków grupy do „posiadania” tego, że ich kod jest czytelny dla innych - oznacza to, że za każdym razem, gdy ktoś zadaje pytanie o Twój kod, zobowiązujesz się dokonać zmiany - lub lepiej połączyć go z tym osoba, która dokona zmiany w tym momencie!

Poważnie zastanów się nad naciskiem na to w ramach „umowy zespołowej” (i zdecydowanie stwórz umowę, jeśli jej nie masz) - w ten sposób wszyscy się zgodzili i masz ją gdzieś na ścianie, aby nie było t jakiekolwiek pytanie dotyczące tego, co zgodziłeś się zrobić.

Może ten facet powinien docenić dobrą dyscyplinę kodowania i dlaczego ważne jest, aby inni ludzie mogli zrozumieć kod, który napisał.

W swojej karierze pracowałem nad naprawdę okropnymi bazami kodowymi, takimi, w których kod był tak źle zorganizowany, nazwy zmiennych były tak kiepskie, komentarze tak kiepskie lub nie istniały, że baza kodowa zaszkodziła mojej produktywności. Nie możesz pracować nad naprawą lub ulepszeniem bazy kodu, której nie rozumiesz, a jeśli jest napisany w sposób, który jest niedostępny dla początkujących, spędzą więcej czasu próbując go zrozumieć, niż faktycznie nad nim pracować.

Nie ma lepszego nauczyciela niż trudne doświadczenie!

Każda baza kodu zawiera jakieś okropne fragmenty, części systemu, których nikt nie chce dotknąć, ponieważ boją się czegoś złamać lub nie mogą wykonać żadnej znaczącej pracy, ponieważ ktokolwiek napisał kod, odszedł i zrozumiał kodu razem z nimi. Jeśli ten kod nie jest komentowany i nie jest samodokumentujący, to tylko pogorszy sprawę.

Sugeruję, abyś znalazł kawałek swojej bazy kodu, który jest taki, i powierzył ci za to kłopotliwą programistę. Daj mu własność, powierz mu swoją odpowiedzialność, pozwól mu nauczyć się prawdziwego bólu związanego z pracą nad kodem, którego nie można utrzymać, ponieważ nie jest on dobrze udokumentowany lub niemożliwy do zrozumienia w krótkim czasie. Po kilku miesiącach pracy nad tym, jestem pewien, że zacznie się pojawiać.

Daj mu jeszcze jeden kod bez komentarzy i poproś go o zrozumienie kodu. Być może zrozumie wtedy znaczenie poprawnych komentarzy.

Czy ten programista zajmuje się konserwacją kodu? Jeśli nie, powinien: sprawdzić, czy istnieje jakiś nielubiany projekt i powierzyć mu jego obsługę.

Zwykle są to źle udokumentowane projekty, w których tracisz godziny próbując zrozumieć, co się dzieje, aby poprawić to, co można łatwo naprawić. Jeśli tego rodzaju doświadczenie nie powoduje, że chce być na bieżąco, poprawna i użyteczna dokumentacja nic nie będzie.

W jednym z moich poprzednich projektów brakowało dziesiątek komentarzy (algorytm, wyniki lub podstawowe JavaDoc), więc właśnie postanowiłem zrobić dla niego 130 spraw, a powiadomienia o każdym z nich będą wysyłane pocztą elektroniczną co 4 dni. Po 3 tygodniach miał 280 numerów, a potem postanowił napisać komentarz.

Komentarze mają jeden cel i tylko jeden cel:

Dlaczego ten kod to robi?

Jeśli komentarz nie wyjaśnia, dlaczego coś jest tak, to należy go usunąć. Bezużyteczne komentarze zaśmiecające kod są mniej niż bezużyteczne, są aktywnie szkodliwe.

Mam w zwyczaju, aby moje komentarze były najbardziej oczywistą rzeczą w moim IDE. Są podświetlone białym tekstem na zielonym tle. Naprawdę przyciągają twoją uwagę.

Jest tak, ponieważ kod wyjaśnia, co coś robi, a komentarze dotyczą tego , dlaczego to robi. Nie mogę tego wystarczająco podkreślić.

Dobry przykład komentarza:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Zły przykład:

/* instantiate clsUser */

Jeśli używasz komentarzy jako „sekcji” kodu: Posiekaj swoją mamutą metodę na mniejsze przydatne funkcje nazwane i usuń komentarze.

Jeśli mówisz, co robisz w następnym wierszu: uczyń kod zrozumiałym i usuń komentarz.

Jeśli używasz komentarzy jako komunikatów ostrzegawczych: upewnij się, że powiesz dlaczego.

Aby uzupełnić odpowiedzi tutaj, mogę dodać „Jeśli chcesz, aby to zrobiono dobrze, musisz to zrobić sam”.

Nie mam na myśli zostać „głównym komentatorem kodu”, mam na myśli stać się wzorem do naśladowania w zademonstrowaniu tego, co chciałbyś zrobić inny programista. Mówią, że pokazywanie jest bardziej skuteczne niż mówienie . Jeśli możesz zademonstrować zalety wysokiej jakości komentarzy, lub nawet mentorować tego innego programistę (w zakresie, w jakim jest on chętny), możesz odnieść większy sukces w przyjmowaniu komentarzy do kodu.

Podobnie w domu są prace domowe, których nie dbam. Jednak te same obowiązki okazują się być obowiązkami mojej żony ... narzekania, które należy wykonać, aby mogła być szczęśliwa. Ta sama sytuacja obowiązuje odwrotnie. Myślę, że być może będziesz musiał zaakceptować fakt, że ten inny programista ma inne priorytety niż ty i nie zgodzi się z tobą we wszystkim. Rozwiązaniem, które znaleźliśmy z moją żoną, jest to, że w przypadku tych „domowych wkurzania” musimy po prostu sami je wykonać, nawet jeśli oznacza to trochę więcej pracy na własną rękę.

Proste: jeśli pracownik nie komentuje, powiedz mu, aby naciskał shift+alt+jna automatyczny komentarz w każdej metodzie jednocześnie z wprowadzeniem kodu. zrób poprawkę kodu, aby uniknąć tych problemów.