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

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.

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.

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.

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.

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

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

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

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.