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

182

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ć?

Mahbubur R. Aaman
źródło
109
Komentowanie ze względu na komentarze nie poprawia kodu. Jeśli kod jest zrozumiały (w tym dlaczego) bez komentarzy, to w przeciwnym razie dobrze skomentuj.
Martin York
63
O tak, a kiedy złożoność jakiegoś fragmentu kodu potroi się w celu rozwiązania warunków wyścigu lub impasu, nie komentuj tego! Pozwól ludziom rozwiązać zagadkę, dlaczego kod musi być taki, jaki jest i dlaczego łamie się w tajemniczy sposób, jeśli wprowadzają eksperymentalne zmiany. Każdy powinien być szachowym arcymistrzem współbieżności ...
Kaz
12
@Kaz Sarcasm (mam nadzieję) nie przekłada się dobrze na tekst.
deworde
10
@deworde & artjom - tak, to jest sarkazm. nie, to nie wygląda tak czysto, jak mogłoby, ale to wyraźnie sarkazm.
17
zgodnie z zasadą Dale'a Carnegiego powinieneś spróbować zrozumieć, dlaczego nie chce komentować .. wspomniałeś, że nie chce opóźniać projektu .. więc możesz mu powiedzieć, że jeśli nie skomentuje, inni nie będą w stanie zrozumieć kod, a to dodatkowo opóźniłoby projekt ... to zdecydowanie powinno pomóc ..
Anirudha

Odpowiedzi:

430

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.

tdammers
źródło
269
+1 za „nie narzekaj na brakujące komentarze: narzekaj na nieczytelny kod”.
Md Mahbubur Rahman,
4
Co jeśli odpowiedź na dowolne pytanie dotyczące kodu brzmi „Co zrobiłeś, aby go zrozumieć?”
Saul
40
+1: Naciskanie na czytelne nazwy funkcji może mieć dodatkowe zalety ... W Code Review: „Nie mogę zrozumieć, co robi xg_jkhsfkasq”. „Och, opróżnia główny bufor, teraz mogę zwolnić?” „Jasne, ale jestem niezdecydowany, aby zatwierdzić to, dopóki nie zmienisz nazwy funkcji flush_primary_buffer” „Ach, ale to także czyści główną pamięć podręczną, więc ta nazwa wprowadzałaby w błąd” „TO CO? Nie usuwaj tej pamięci podręcznej, to „Zatrzymasz system!” Zmieniając tę ​​logikę, czy miałbyś coś przeciwko zmianie nazwy tej funkcji? ”
deworde
18
Martwiłbym się sprawianiem wrażenia, że ​​nie jestem w stanie odczytać kodu. Nietechniczny menedżer może po prostu zauważyć, że stale pytam „Boba” o pomoc, ponieważ kod Boba jest dla mnie zbyt zaawansowany. Oznaczałoby to, że Bob jest „zaawansowanym” programistą i nie jestem gotowy do pracy na jego poziomie.
Rob P.
5
@Rob P. Widzę strach, ale jeśli nie możesz odczytać kodu i oczekuje się, że będziesz go utrzymywał, to kod nie jest dobrze napisany lub nie wiesz wystarczająco dużo. Jeśli nie wiesz wystarczająco dużo, musisz zapytać. Jeśli pytanie ujawni, że kod jest po prostu trudny do odczytania, poproś o jego naprawienie. Sztuką byłoby, jeśli idziesz ścieżką inżynierii społecznej, mieszać ją bez względu na to, czy Bob idzie do twojego biurka, czy idziesz do niego, i bardzo aktywnie wskazywać na rzeczy. W końcu menedżer niezwiązany z technologią nie będzie w stanie zrozumieć treści dyskusji ...
deworde
114

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.

Doc Brown
źródło
5
+1 jest to jedyny sposób na faktyczną zmianę wprowadzoną przez współpracownika, którą znalazłem, usiądź z nim i sprawdź / przeprowadź refakturę obok nich. Jeśli nie możesz odmówić przeglądu kodu, może to być trudne. Czasem, kiedy jesteś średniego szczebla po prostu trzeba podnieść kwestie seniorów i jeśli nie będą słuchać szlifować swój nos na zewnątrz dopóki jesteś starszy i może zawetować taki śmieci
Jimmy Hoffa
1
Recenzje kodu i programowanie par to najlepszy sposób z mojego doświadczenia w podnoszeniu ogólnego poziomu programistów w zespole. Chodzi o dzielenie knoledge i umiejętności w zespole. Bez tego sprawiasz, że programiści uczą się na własnej skórze i zakładają, że wyszli z college'u perfekcyjnie. Ogólny brak tej praktyki w branży jest prawdopodobnie przyczyną, dla której jest tak wielu programistów z ponad 10-letnim doświadczeniem, którzy nie potrafią napisać czytelnego, dobrze zorganizowanego kodu.
Martin Brown
27

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)

Earlz
źródło
2
+1 - Jeśli musisz zadać pytanie dotyczące dowolnej części kodu, ta część wymaga komentarza lub refaktoryzacji, aby pytanie nie musiało być zadawane przez kogoś innego w przyszłości.
Dunk
+1 Również zaskakujące recenzje kodu / recenzentów są tak nisko w dół odpowiedzi. Wdrożenie recenzji kodu na poziomie zespołu (aby nie wybierać poszczególnych osób) może pomóc w rozwiązaniu problemu (a może innym, o których nawet nie wiesz, że masz :). Skrajnie możesz wdrożyć zasadę „nie pchaj solo”, zgodnie z którą nie możesz pchać, chyba że zmiany zostały sprawdzone przez innego członka zespołu.
Chris Lee
@ChrisLee w mojej firmie zasady sprawdzania kodu firmy nie są egzekwowane technicznie, ale istnieje zasada, że ​​zanim artykuł może zostać oznaczony jako gotowy do testu, musi zostać poddany przeglądowi kodu, bez względu na to, kto wykonał prace programistyczne. Interesujące jest recenzowanie kodu, gdy CTO dokonuje odprawy przez lol
Earlz 17.09.13
18

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ę.

Szczery
źródło
+1 za omówienie faktycznych zysków z komentarzy. Komentarze mają na celu zwiększenie wartości kodu źródłowego.
Sparky,
1
Re: „tego rodzaju zmuszanie najprawdopodobniej spowoduje okropne komentarze”. Jeśli nie komentujesz podczas pisania kodu, uzupełnianie komentarzy po zakończeniu kodu prawie zawsze spowoduje okropne komentarze, niezależnie od tego, czy w nie wierzysz. Kiedy kodujesz, jest to czas, w którym dokładnie wiesz DLACZEGO robisz coś w określony sposób. To czas, aby poinformować innych. Jeśli komentujesz po zakończeniu, istnieje prawdopodobieństwo, że nawet nie pamiętasz, co myślałeś podczas pisania kodu, więc zwykle rzucasz bezużyteczny komentarz tylko ze względu na komentarz.
Dunk
3
zawsze miał problem z podejściem do tej książki. Komentarze mogą być bardzo przydatne w wyjaśnianiu procesów biznesowych / logiki (lub dlaczego), których nie potrafi żadna ilość czystego kodu.
bharal
Chociaż komentarze w kodzie nie byłyby konieczne, powinien istnieć przynajmniej opis metody, na przykład Javadoc
Danubian Sailor
2
Czysty Kod to przyzwoita książka, ale nie należy jej traktować jak ewangelii. Musisz kierować się zdrowym rozsądkiem i sam zdecydować, co działa. Nie zgadzam się z poradami na temat komentarzy, ponieważ języki programowania są ukierunkowane na wyrażenie problemu ze skromnym uwzględnieniem przyczyny. Pisałem kod do Zakupów Google, który dołącza kod kraju do SKU produktu. To oczywiste, co robi kod, ale jeśli nie wiesz, że możesz użyć tego samego kodu produktu tylko raz, nawet na różnych rynkach, nie wiedziałbyś, dlaczego to robię. Komentarz, który dodałem, wyjaśnia to.
GordonM,
10

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.

kojiro
źródło
3
Nie sądzę, aby groźby były z konieczności skuteczne, mogą być postrzegane jako zastraszanie (nawet jeśli nie taka była ich intencja), a koderzy z reguły są niechętni edyktom z wyższych stanowisk iw tym przypadku może po prostu wbij jeszcze więcej obcasów. Może dojść do tego w ostateczności, ale tylko w ostateczności.
GordonM,
@GordonM Czy uważasz, że lepiej byłoby nie informować pracownika, kiedy jego zachowanie jest nieodpowiednie i jakie byłyby konsekwencje dalszego niewłaściwego zachowania?
kojiro
Oczywiście nic nie mówienie nie jest dobrym pomysłem, ale grożenie ludziom będzie sprzyjać klimatowi strachu, zwłaszcza w stosunku do względnie drobnych rzeczy, takich jak styl komentowania. Jeśli wytłumaczysz mu rozsądnie, dlaczego zespół uważa komentowanie za ważne, to w porządku. Ale wiem, że jeśli ktoś zagroziłby mi workiem na coś stosunkowo niewielkiego, byłbym bardziej skłonny po prostu zacząć szukać innej pracy.
GordonM,
@GordonM Właściwie biorę wyjątek od implikacji, że to, co powiedziałem, było groźne, ale i tak to naprawiłem.
kojiro
8

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.

rev Danny Tuppeny
źródło
4

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).

Yauhen Yakimovich
źródło
Możesz pisać kod, który nie wymaga komentarzy tylko dla zabawy. To może być świetne ćwiczenie, ale nie, jeśli musisz wrócić do kodu i nie możesz tak naprawdę nic zmienić, ponieważ nie będziesz wiedział, dlaczego ta funkcja działa, ponieważ może być jakiś klient, który tego chciał. Oczywiście możesz być w tym być może 1% projektu, który jest udokumentowany i uzasadniony poza projektem, ale nawet wtedy są decyzje, które podejmujesz podczas kodowania, a które nie wracają do dokumentacji. I szczerze mówiąc ... Kto czyta dokumentację, której nie ma w kodzie. Z pewnością nie programiści ;-P.
Nux
1
Dobry inżynier dba o cały system (w tym dokumentację niekodowaną) - ale tutaj oczywiście ogólnie kodujemy w myślach .. Chodzi mi o to, że brak identyfikatorów w kodzie o nazwie foo , bar , tmpSomething2 i IamJustTooSmartAssToCare już się poprawia sytuacja i zmniejsza ogólną potrzebę wyjaśnienia, czym jest kod i co robi. Kod powinien być napisany z „włączonym trybem myślenia”, podobnie jak dobrze zaprojektowany interfejs API, który jest czytany, rozumiany, ponownie wykorzystywany i obsługiwany przez ludzi. Zbyt wiele komentarzy w kodzie, które w innym przypadku byłyby trudne do zrozumienia, jest bardzo złym znakiem!
Yauhen Yakimovich
BTW programowanie / kodowanie dowolnego rodzaju logiki specyficznej dla domeny w postaci HACK-a lub „tymczasowej” naprawy błędu powoduje w rzeczywistości „dziwne HACK-y” - gdy tylko wiele z nich zostanie wciśniętych w blackbox - spodziewaj się, że zawieść i odpalić. Można to uzasadnić terminami w projektach „w realnym świecie” itp. ale w rzeczywistości jest to po prostu tanie oprogramowanie, które wymaga przebudowy logiki domeny (lub może znalezienia nowej pracy).
Yauhen Yakimovich
Zgadzam się, że czytelność jest ważna. Nie zgadzam się z tym, że wydajesz się mówić „jeśli priorytetem jest czytelność, nie będziesz potrzebować komentarzy”. To po prostu nieprawda. Zostałem tam zrobiony. Rozumowanie tego, co robisz, nie wynika tylko z nazewnictwa zmiennych w sposób, który ma sens. Zrób to oczywiście, ale dodaj również powód w komentarzach (nawet jeśli ma on postać numeru błędu / wymagania / historii w jakimś systemie zewnętrznym). Tak mówię.
Nux
„jeśli uczynisz czytelność priorytetem, nie będziesz potrzebować komentarzy” - tak właśnie to mówię (i wiem, że nie wydaje się to łatwe do osiągnięcia). BTW Czy zdarzają się sytuacje, w których utrzymywanie pełnej historii zatwierdzeń (kontroli wersji) nie wystarcza do refleksji nad „błędem / wymaganiem / numerem historii”? Ćwiczyłem raczej długie zobowiązania - działa dla mnie i pozwala zachować pusty kod z historii programowania .. sprawia, że ​​jest mniej ekologiczny.
Yauhen Yakimovich
3

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.

Pete
źródło
Programowanie w parach jest doskonałym pomysłem, daje innemu programistowi wgląd w rozwój kodu, dzięki czemu wie, co się dzieje, dzięki czemu dwie osoby są odpowiedzialne za kod. daje również szansę jednemu z nich na powiedzenie, że coś powinno mieć komentarz, ponieważ jest czymś niezwykłym lub czymś, co ktoś inny może zmienić, ponieważ wygląda na… „wyciek pamięci”, „złe kodowanie”, itd. niektóre rzeczy wymagają komentarza, aby ktoś w przyszłości nie cofnął niczego, ponieważ nie wygląda to dobrze.
Malachi
3

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ć!

Paul
źródło
4
To jest po prostu głupie. Mam nadzieję, że nikt nie wierzy, że taki kiepski styl komentowania jest pomocny. Ale czy naprawdę wierzysz, że nigdy nie należy używać komentarzy ?
jmk
1
Tak, to głupia sugestia, jeśli kod jest niewiarygodnie czytelny, mógłbym zrozumieć kilka komentarzy, ale zobaczenie komentarzy powinno powiedzieć, dlaczego metoda robi to, co jest i gdzie będzie używana, gdy dojdziesz do więcej niż kilku klas, naprawdę jest bez powodu bez komentarzy, pomagają wszystkim.
DBlackborough
3
Ważną rzeczą do zapamiętania jest to, że chociaż wszystko ma dla ciebie teraz sens, ktoś inny będzie musiał utrzymać Twój kod za 3 lata. Nie przekręcaj.
xaxxon
4
@xaxxon Nie wspominając o jabłkach, nawet jeśli ta osoba może być tobą.
puszysty
3
@mehaase - Nie co, nie jak, ale dlaczego jest najważniejszym powodem dodawania komentarzy do kodu.
Henk Langeveld
1

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.

Brendan
źródło
1

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ą?

LJ2
źródło
Kiedy pokój pełen ludzi zacznie się śmiać z twojego nieczytelnego kodu, zaczniesz lepiej kodować i komentować. :) Jestem wielkim zwolennikiem recenzji kodu.
Evik James
1
Ludzie nie śmieją się z kodu przed innymi kolegami: - \
Danny Tuppeny,
1
Jeśli osoby dokonujące przeglądu kodu śmieją się, a nie są konstruktywne, potrzebują szkolenia tak samo, jak programista, który nie umie napisać czytelnego kodu. Krytykowanie, które jest konstruktywne, a nie obraźliwe, jest jedną z umiejętności społecznych, których często brakuje deweloperom.
Martin Brown
1

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.

Bill
źródło
0

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.

mouviciel
źródło
6
Nie, w ten sposób programiści muszą pisać jakieś komentarze. Ich przydatność maleje wraz z naciskiem na ich pisanie, często pogrążając się poniżej zera w aktywnie szkodliwym regionie (niepoprawny komentarz jest gorszy niż brak komentarza), jeśli polityka zostanie silnie poparta.
Jan Hudec
1
@JanHudec - Zgadzam się z tobą. Dlatego należy ustawić kontrolę. Automatyczne generowanie zapewnia, że ​​np. Argumenty funkcji w kodzie są takie same jak w komentarzach. Co więcej, posiadanie jednego pliku PDF zamiast katalogu plików źródłowych sprawia, że ​​dokumentacja jest bardziej czytelna (tj. Bardziej dostępna do przeglądania) przez większą liczbę osób.
mouviciel
2
No nie, nie ma. Jak zauważysz w pliku .pdf, że kod rzeczywiście robi coś subtelnie innego niż ten opis?
Jan Hudec
1
Być może moja opinia jest stronnicza z powodu mojej domeny, oprogramowania o krytycznym znaczeniu dla przestrzeni, w którym wszystko jest sprawdzane, kontrolowane, weryfikowane, testowane dwa lub trzy lub cztery razy. Automatyczne generowanie dokumentacji nie eliminuje niespójności, ale pomaga je zmniejszyć.
mouviciel
Tak, jesteś bardzo stronniczy. W takich domenach ma to sens, w większości testów jednostkowych wystarcza do zapewnienia jakości, a dokumentowanie każdej ostatniej funkcji byłoby stratą czasu.
Jan Hudec
0

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.

reinierpost
źródło
0

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
rev. M.S. Mayak
źródło
0

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ć.

Bill K.
źródło
0

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ć.

GordonM
źródło
-1

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

Abhishek Gahlout
źródło
12
Ledwo uniknąłem przy tym przycisku -1. Większość kodu, który piszę, ma bardzo niewiele komentarzy. Nie sądzę, żeby ludzie narzekali, że przynajmniej przez ostatnie kilka lat nie jest to zrozumiałe. Z nielicznymi wyjątkami, jeśli kod wymaga komentarza do zrozumienia , to nie potrzebuje komentarzy, wymaga poprawy w celu zachowania przejrzystości. (Oczywiście musisz założyć podstawową znajomość składni języka. Na przykład, w C ++, nie wychodź z drogi po prostu, aby uniknąć używania, reinterpret_cast<>()ponieważ ludzie mogą uznać to za mylące; w C #, jeśli ??robi to, czego potrzebujesz, użyj it; itp.)
CVn
2
@ MichaelKjörling: Może to zależeć w dużym stopniu od rodzaju pisanego kodu. Jeśli Twój kod zależy od nieznanych cech języka lub interfejsu API lub zrobiłeś coś w sposób sprzeczny z intuicją, aby uniknąć niejasnego błędu, którego wykrycie zajęło wiele godzin, o wiele skuteczniej byłoby komentować to (prawdopodobnie zawierające link do artykułu) niż próba uczynienia kodu „jasnym” na temat tych informacji w tle bez komentarzy.
LarsH
@ MichaelKjörling: Jestem szczególnie zmotywowany, aby powiedzieć to dzisiaj, ponieważ walczyłem przez ostatni miesiąc z głębokim interfejsem GIS API. Funkcje API są złożone i niezbyt dokładnie udokumentowane. Ciągle napotykamy niespodzianki, z których niektóre cofają się o kilka dni. Oczekiwanie, że ktoś inny (lub ja za 6 miesięcy) będzie musiał ponownie odkryć te samorodki, aby skutecznie pracować z naszym kodem, byłoby ogromną stratą czasu tej osoby. Tych tajemnic na ogół nie da się udokumentować bez komentarza „poprawą dla przejrzystości”.
LarsH
@LarsH To prawdopodobnie kwalifikuje się jako jeden z „bardzo niewielu wyjątków”, o których wspomniałem w moim komentarzu. Nie jestem przeciwny komentowaniu, gdzie to rzeczywiście dodaje wartości ; ale to nie ilość komentarzy sprawia, że ​​kod jest łatwy lub trudny do odczytania. To powiedziawszy, z API, byłbym bardziej skłonny dokumentować te dziwactwa gdzie indziej; powiedzmy na wiki lub podobnym. Może także dodać link do odpowiedniej strony obok każdego użycia. W ten sposób nie musisz szukać innego miejsca, które korzysta z tej konkretnej funkcji interfejsu API, ilekroć kod nie działa tak, jak oczekujesz przy pierwszej próbie.
CVn
@ MichaelKjörling: ogólnie uzgodnione. To, czy te wyjątki są rzadkie, czy nie, zależy od domeny, dla której programujesz, oraz interfejsów API, których musisz użyć. Linki / odniesienia są dobre dla notatek, które mają zastosowanie ogólnie, nie tylko do bieżącej sytuacji. Nikt nie chce rozprawy w samym kodzie.
LarsH
-1

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.

Arkh
źródło
1
Podejście to jest bardziej skłonne do tego, aby programista zakończył pracę, niż szkolił go w zakresie właściwego działania.
Martin Brown
-1

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.

agilob
źródło
-1

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.

Jonathan
źródło
-2

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ę.

M. Dudley
źródło
1
Twierdziłbym, że pokazanie czystszego kodu / refaktoryzacja kodu, aby były bardziej czytelne, pokazuje większą zmianę niż umieszczanie w kodzie mnóstwa komentarzy.
Makoto
Czy ktoś może mi wyjaśnić, czego nie lubi w moim pomyśle ...?
M. Dudley
-6

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.

Peter
źródło
11
„Auto komentarz”? Tak to jest , gdy wszystkie te „inkrementacja i przez 1” komentarze pochodzą? Które IDE to robi (aby uniknąć zadań, w których jest używany)?
CVn
Próbowałem zmienić to w coś czytelny, ale nie jestem pewien, czy słowo pierwszy powinien mieć przecinek przed nim lub po nim. Czy fraza komentuje każdą metodę jako pierwszą czy pierwszą ?
TRiG