Czy więcej komentarzy jest lepszych w środowiskach o wysokich obrotach?

11

Rozmawiałem dziś z kolegą. Pracujemy nad kodem dla dwóch różnych projektów. W moim przypadku jestem jedyną osobą pracującą nad moim kodem; w jej przypadku wiele osób pracuje na tej samej bazie kodu, w tym studenci kooperacyjni, którzy przychodzą i odchodzą dość regularnie (co 8-12 miesięcy). Powiedziała, że ​​jest liberalna ze swoimi komentarzami, umieszczając je wszędzie. Jej rozumowanie polega na tym, że pomaga jej pamiętać, gdzie są rzeczy i co robią, ponieważ znaczna część kodu nie została napisana przez nią i może zostać zmieniona przez kogoś innego niż ona. Tymczasem staram się minimalizować komentarze w moim kodzie, umieszczając je tylko w miejscach z nieoczywistym obejściem lub błędem. Jednak lepiej rozumiem mój kod i mam większą bezpośrednią kontrolę nad nim.

Moje zdanie w tych komentarzach powinno być minimalne, a kod powinien opowiadać większość historii, ale jej rozumowanie również ma sens. Czy w jej rozumowaniu są jakieś wady? Może zaśmiecać kod, ale ostatecznie może być bardzo pomocny, jeśli pracuje nad nim wiele osób w krótkim lub średnim okresie.

joshin4colours
źródło
8
Jak myślisz, co się stanie, kiedy przejdziesz do innego projektu lub innej pracy i ktoś inny będzie musiał zachować Twój kod? Czy Twój kod jest naprawdę tak czysty i przejrzysty, że ktoś inny łatwo zrozumie, co robisz i dlaczego?
Caleb
2
Wiele dobrych odpowiedzi w istniejących odpowiedziach. Chciałem tylko powiedzieć, że jeśli jest teraz kilka testów jednostkowych, poświęć czas na testy budowlane, a nie na komentarze, w środowisku o wysokich obrotach. Jeśli pozostało jeszcze czasu na komentarze, dodaj komentarze „dlaczego” zarówno do kodu, jak i do testów.
James Youngman
@Caleb Nawet jeśli nie było to czyste i jasne, czy naprawdę uważasz, że pomocne mogą być rozpraszające komentarze w tym miejscu? Dlaczego nie napisać dokumentacji w innym miejscu z opisem?
joshin4colours

Odpowiedzi:

22

Komentarze nie zaśmiecają kodu.

A kiedy to robią, cóż, co pół przyzwoitego IDE może ukrywać / fałszować komentarze. Idealnie, historia powinna być opowiedziana przez kod, dokument wymagań, historię zatwierdzeń i testy jednostkowe, a nie komentarze. Jednak nadmierne komentowanie może zaszkodzić tylko wtedy, gdy komentarze koncentrują się na tym, jak, a nie na tym, dlaczego, ale to inna dyskusja .

Myślę, że zarówno ty, jak i twój kolega macie „rację”, z tą różnicą, że pracujesz sam, a ona w zespole, który często obejmuje niedoświadczonych programistów. Nie masz tak różnej filozofii komentarzy, ale bardzo różne wymagania dotyczące przekazywania kodu. Argument „pomaga mi zapamiętać” może również wynikać z faktu, że zajmuje się znacznie większą ilością kodu niż ty, a co ważniejsze, kodem tworzonym przez różnych ludzi, z których każdy ma swoje osobiste preferencje i dziwactwa.

Pod koniec dnia komentarze do kodu, choć ich oczywiste wady, są najprostszym i najszybszym sposobem na przekazanie kodu. W zależności od składu zespołu i organizacji może to być jedyny sposób, który dotyczy najniższego wspólnego mianownika. Zwykle podążam za twoją filozofią komentowania, gdy pracuję sam i dostosowuję się do twojego kolegi, kiedy pracujesz w zespole, szczególnie jeśli jest to niezrównoważone umiejętności zespołu.

Yannis
źródło
9
+1 na Excessive commenting can only hurt when comments are concentrated on the how and not the whytyle, że posunę się o krok dalej i powiem, ŻADNE komentarze są złe, gdy wyjaśniają, jak zamiast tego .
wałek klonowy
Comments don't clutter the code.To zależy, szczególnie jeśli używasz #.
Dynamiczny
11

Odpowiednie komentarze w tego rodzaju środowisku kryją problem, który należy rozwiązać w inny sposób.

Jakość, czytelny kod nigdy nie powinien wymagać dodatkowych komentarzy, aby wyjaśnić, co robi. Jedyny czas na komentarz to wyjaśnienie, dlaczego coś zostało zrobione w określony sposób. I nawet wtedy te komentarze mogą być prawdopodobnie w komunikatach zatwierdzania kontroli źródła.

Problem, który rozwiązuje, polega na tym, że musi pracować z uczniami, którzy nie wiedzą, jak napisać swój kod w czytelny sposób. Moim zdaniem zaśmiecanie kodu komentarzami jest słabym rozwiązaniem tego problemu.

Rygorystyczne przeglądy kodu byłyby znacznie bardziej skuteczne, zarówno w utrzymywaniu porządku w kodzie, jak i ulepszaniu tych studentów na przyszłość, czy to w tej samej firmie, czy gdzie indziej.

pdr
źródło
6
Dokładna recenzja kodu powinna zakwestionować nadmierne komentarze programisty, ale masz całkowitą rację, że jej zespół skorzystałby znacznie więcej na regularnych recenzjach kodu niż na mnogich komentarzach.
wałek klonowy
4
„Czytelny kod wysokiej jakości nigdy nie powinien wymagać dodatkowych komentarzy w celu wyjaśnienia, co robi”. - Co nie jest prawdziwe w przypadku 90% napisanego kodu.
Oliver Weiler
1
@OliverWeiler: Tak więc 90% napisanego kodu może zrobić z dobrą recenzją kodu. Miałem 5 starszych programistów w zespole, w których cały kod został sprawdzony przez co najmniej jednego innego starszego programistę, w wyniku czego stworzyli bardzo czytelny kod, przy minimum komentarzy.
pdr
1
@pdr Dla wielu zespołów i większości aplikacji założenie najlepszego scenariusza w zakresie jakości i czytelności kodu jest katastrofą. Wszyscy uważają, że ich kod jest całkowicie zrozumiały. Prawda w tej sprawie jest często bardzo różna.
Dave
1
@Dave: Nie sugeruję, że powinieneś cokolwiek zakładać. Sprawdzasz jakość kodu, przekazując go innemu deweloperowi i mówiąc „czy możesz to przeczytać i zrozumieć?” Która jest o wiele bardziej niezawodną wytyczną niż „Mam nadzieję, że dzięki tym komentarzom można ją odczytać” i ma szybszą pętlę sprzężenia zwrotnego (tj. Możesz przepisać kod lub dodać komentarz, dopóki jest on w twoim umyśle).
pdr
6

Problem z komentarzami polega na tym, że bardzo szybko stają się one niezsynchronizowane z kodem. Oznacza to, że w kodzie często pojawiają się mylące lub całkowicie błędne komentarze, więc bardziej ograniczają czytelność niż pomagają.

Celem jest ułatwienie zrozumienia i modyfikacji bazy kodu. Możesz to zrobić, chociaż możesz swobodnie korzystać z komentarzy (choć możesz napotkać problem z komentarzami do danych), lub możesz napisać samodokumentujący kod (o ile to możliwe) i używać komentarzy tylko do wyjaśnienia nietrywialnego „dlaczego " pytania. Każde z tych podejść może działać, ale pamiętaj, że aby zmodyfikować kod, musisz zrozumieć sam kod, a nie tylko komentarze. Tak więc komentarze mogą pomóc ci zrozumieć kod, ale na koniec dnia prawdopodobnie będziesz musiał zrozumieć sam kod. Powiedziawszy to, wolę podejście oparte na samodokumentowaniu. Wydaje się, że jest to bardziej bezpośredni sposób na stworzenie czystej bazy kodu.

Oleksi
źródło
5

„Czy więcej komentarzy jest lepszych w środowiskach o wysokich obrotach?”

Myślę, że mogą być gorsze:

  • Różni autorzy będą używać różnych stylów i poziomów szczegółowości i mniej będą chcieli aktualizować komentarze innych osób.

  • Opinia „Co wymaga komentowania” zmienia się w zależności od osoby.

  • Kontynuują praktykę pisania kodu, który jest trudny do odczytania z komentarzami, aby go wyjaśnić, w przeciwieństwie do kodu łatwego do odczytania z opisowymi nazwami.

  • Utrzymanie ich formatu i spójności staje się zadaniem samym w sobie.

  • Nowi użytkownicy muszą nauczyć się standardu „formatu”, zanim będą mogli wprowadzać szybkie zmiany.

Michael Durrant
źródło
3
Problemy, które wymieniasz, dotyczą także samego kodu w środowisku o wysokiej rotacji, a nie tylko komentarzy. To ... ciekawe;) Bardziej problem związany z ludźmi, niż problem z kodem / komentarzem.
yannis
+1 Cześć Yannis, tak, to bardzo dobra uwaga. Zgadzam się. Myślę też, że ponieważ sam kod jest trochę bardziej ustrukturyzowany - ma ustalone nazwy dla niektórych rzeczy, najprostszy przykład - funkcja „to_string” nie ma dwuznaczności, należy ją nazwać tam, gdzie jako komentarze mają absolutnie zerową strukturę lub uzgodnione warunki , co sprawia, że ​​komentarze są kłopotliwe. Z drugiej strony kod może skończyć się o wiele bardziej „spaghetti” niż komentarzami. Ciekawy.
Michael Durrant
4

Punkt 1: Przejrzystość jest ważna w środowiskach o wysokich obrotach

Punkt 2: Szczegółowość nie jest klarownością

Dodanie komentarzy do kodu może, ale nie musi, poprawić jasność; zależy to od dodanych komentarzy. Po osiągnięciu optymalnej przejrzystości dodatkowe komentarze pogorszą sytuację, a nie poprawią.

Podczas gdy komentarze są elementem przejrzystości, jakość kodu jest znacznie ważniejszym elementem. Spryt jest przeciwieństwem jasności . Jeśli funkcja kodu nie jest od razu widoczna podczas zwykłego czytania, to kod nie jest szczególnie przejrzysty, a komentarze (bez względu na to, jak wysokiej jakości są komentarze) są złym i nieskutecznym substytutem czystego kodu.

Na przykład upychanie flagi w wysokiej bicie niezwiązanego pola może być w pewnych okolicznościach doskonale dopuszczalne i może mieć sens z perspektywy wydajności w pewnych okolicznościach, ale jest to zawsze zły pomysł pod względem przejrzystości , nawet jeśli komentujesz to do diabła.

Jeśli musisz wyjaśnić proza, czym zajmuje się Twój kod, zastanów się nad jedną z następujących rzeczy: Pamiętaj, że niektóre z nich mogą wpływać na wydajność, ale w niektórych przypadkach wydajność może nie być tak ważna jak przejrzystość.

  • Lepsze nazwy zmiennych i nazwy funkcji
  • Lepszy układ kodu i odstępy
  • Usuń wszelkie „sztuczki”, które Twoim zdaniem były dobrym pomysłem
  • Grupuj kod według funkcji pojęciowej (np. Wyodrębnij kod dla określonego celu w funkcję o odpowiedniej nazwie, nawet jeśli wywołasz go tylko raz)
  • Użyj prostszego algorytmu (jeśli pozwalają na to warunki)
  • Używaj dobrze znanych bibliotek dla wspólnej funkcjonalności
tylerl
źródło
1

Uproszczona odpowiedź: „Im bardziej prawdopodobne jest, że Twój kod zostanie ponownie przeczytany, tym większy będzie ciężar wyjaśniania tego, co robisz”. Może to polegać na ułatwieniu odczytu kodu, komentowaniu go, tworzeniu formalnej dokumentacji, przestrzeganiu standardów stylów ... Pamiętaj, że to Ty możesz ponownie czytać później, choć z pewnością dotyczy to również innych środowisko o wysokich obrotach.

Jest jeszcze jeden świetny wątek, który dotyczy tego, czy komentarze są dokumentacją.

MathAttack
źródło
1

Komentarze są bardziej pomocne w niektórych scenariuszach niż w innych. Jest to tak fundamentalne, że martwię się, jak to wyjaśnić pośród tylu odpowiedzi, które uważam za „anty-komentarz”.

Jeśli Twój kod może nie być czytany przez lata, komentarze są ważniejsze niż w przypadku częstego refaktoryzacji kodu, silnej własności kodu i obszernych recenzji kodu. Jeśli twoja aplikacja jest złożona i wykorzystuje techniki, które nie są od razu oczywiste dla obserwatora biegłego w tym języku, komentarze są ważniejsze niż w przypadku, gdy system jest uwielbionym „Hello World”. Jeśli podstawa kodu nie jest tak rygorystyczna jak na standardy, komentarze są ważniejsze niż w przypadku pracy z sześcioma warstwami kontroli jakości. Jeśli pracujesz w zespole, w którym osiem osób uczy się języka, komentarze są ważniejsze niż w przypadku, gdy Twój zespół ma osiem Pulitzerów programujących. Jeśli na twoich kolanach spadła duża liczba aplikacji,komentarze są ważniejsze niż gdybyś był w stanie zbudować je od zera.

Czy lepiej byłoby w większości tych scenariuszy naprawić przyczynę, zamiast zwiększać wykorzystanie komentarzy? Absolutnie. Ale czasami utkniesz w bazie kodu, która ma więcej odcisków palców niż miejski smartfon, a najlepszym sposobem na jej ulepszenie jest uczynienie twoich zmian możliwie czytelnymi i skomentowanie tego.

Na twój konkretny problem: komentarze nie powinny być tak rozrzucone, aby zaśmiecały kod. Dobrze napisany akapit u góry podprogramu, opisujący, dlaczego funkcja istnieje i może używa tego podejścia, jest często najlepszym rozwiązaniem, aby pomóc następnemu programistowi w ustaleniu orientacji.

Dave
źródło