Co to jest kod samodokumentujący i czy może zastąpić dobrze udokumentowany kod? [Zamknięte]

Mam kolegę, który upiera się, że jego kod nie potrzebuje komentarzy, to „samodokumentowanie”.

Przejrzałem jego kod i chociaż jest on wyraźniejszy niż kod, który widziałem, jak inni go tworzą, nadal nie zgadzam się z tym, że samodokumentujący się kod jest tak kompletny i użyteczny, jak kod z komentarzami i dokumentami.

Pomóż mi zrozumieć jego punkt widzenia.

• Co to jest kod samok dokumentujący
• Czy naprawdę może zastąpić dobrze skomentowany i udokumentowany kod?
• Czy są sytuacje, w których jest lepszy niż dobrze udokumentowany i skomentowany kod
• Czy istnieją przykłady, w których kod nie może być samodokumentujący bez komentarzy

Może to tylko moje własne ograniczenia, ale nie rozumiem, jak może to być dobra praktyka.

To nie ma być argument - proszę nie podawać powodów, dla których dobrze skomentowany i udokumentowany kod ma wysoki priorytet - pokazuje to wiele zasobów, ale nie przekonują one mojego partnera. Uważam, że muszę pełniej zrozumieć jego perspektywę, aby przekonać go, że jest inaczej. Zacznij nowe pytanie, jeśli musisz, ale nie kłóć się tutaj.

Wow, szybka odpowiedź! Proszę przeczytać wszystkie istniejące odpowiedzi i podać komentarze do odpowiedzi zamiast dodawać nowe odpowiedzi, chyba że twoja odpowiedź naprawdę różni się znacznie od wszystkich innych odpowiedzi tutaj.

Także ci z was, którzy sprzeciwiają się kodowaniu samodokumentującemu, mają przede wszystkim pomóc mi zrozumieć perspektywę (tj. Pozytywne aspekty) samodokumentujących ewangelistów kodujących. Oczekuję, że inni będą cię głosować, jeśli nie będziesz kontynuował tematu.

Moim zdaniem każdy kod powinien być samodokumentujący. W dobrym, udokumentowanym kodzie nie trzeba wyjaśniać każdego wiersza, ponieważ każdy identyfikator (zmienna, metoda, klasa) ma wyraźną nazwę semantyczną . Posiadanie większej liczby komentarzy niż to konieczne utrudnia (!) Czytanie kodu, więc jeśli twój kolega

• pisze komentarze do dokumentacji (Doxygen, JavaDoc, komentarze XML itp.) dla każdej klasy, członka, typu i metody ORAZ
• wyraźnie komentuje wszystkie części kodu, które nie są samo-dokumentujące ORAZ
• zapisuje komentarz do każdego bloku kodu, który wyjaśnia zamiar lub sposób działania kodu na wyższym poziomie abstrakcji (tj. znajdź wszystkie pliki większe niż 10 MB zamiast przechodzić przez wszystkie pliki w katalogu, sprawdź , czy rozmiar pliku jest większy niż 10 MB, zwrot wydajności, jeśli prawda )

moim zdaniem jego kod i dokumentacja są w porządku. Zauważ, że samodokumentujący kod nie oznacza, że ​​nie powinno być żadnych komentarzy, a jedynie, że nie powinno być żadnych niepotrzebnych komentarzy. Chodzi jednak o to, że po przeczytaniu kodu (w tym komentarzy i komentarzy do dokumentacji) należy natychmiast zrozumieć, co robi kod i dlaczego. Jeśli kod „samodokumentujący” zajmuje więcej czasu niż kod z komentarzem, tak naprawdę nie jest on samodokumentujący.

Ponieważ chodzi o komentarze i kod, spójrzmy na jakiś rzeczywisty kod. Porównaj ten typowy kod:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

Do tego samodokumentującego się kodu, który pokazuje, co się dzieje:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

A potem do tego udokumentowanego kodu, który lepiej wyjaśnia, dlaczego się to robi:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

I potrzebna jest ostateczna wersja kodu jako dokumentacji z zerowymi komentarzami:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Oto przykład kiepskiego stylu komentowania:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

W ostatnim przykładzie komentarze są używane, gdy zmienne powinny być nazwane opisowo, a wyniki operacji są podsumowane, gdy możemy wyraźnie zobaczyć, co to jest operacja. Wolałbym drugi dokument, który sam sobie udokumentowałem, niż ten, i być może o tym mówi twój przyjaciel, kiedy mówi samodokumentujący kod.

Powiedziałbym, że zależy to od kontekstu tego, co robisz. Dla mnie samodokumentujący się kod jest prawdopodobnie wystarczający w tym przypadku, ale przydatny jest także komentarz opisujący metodologię tego, co jest zrobione (w tym przykładzie równanie).

Sam kod zawsze będzie najbardziej aktualnym wyjaśnieniem tego, co robi twój kod, ale moim zdaniem bardzo trudno jest wyjaśnić zamiary , które są najważniejszym aspektem komentarzy. Jeśli jest napisany poprawnie, wiemy już, co robi kod, musimy tylko wiedzieć, dlaczego on to robi!

Ktoś kiedyś powiedział

1) Pisz tylko komentarze do kodu, który jest trudny do zrozumienia.
2) Staraj się nie pisać kodu, który jest trudny do zrozumienia.

Idea „samodokumentowania” kodu polega na tym, że logika programu w kodzie jest wystarczająco prosta, aby wyjaśnić każdemu czytającemu kod nie tylko to, co robi kod, ale także dlaczego.

Moim zdaniem idea prawdziwego samodokumentującego się kodu jest mitem. Kod może wyjaśnić logikę tego, co się dzieje, ale nie może wyjaśnić, dlaczego robi się to w określony sposób, szczególnie jeśli istnieje więcej niż jeden sposób rozwiązania problemu. Tylko z tego powodu nigdy nie może zastąpić dobrze skomentowanego kodu.

Wydaje mi się, że istotne jest pytanie, czy określony wiersz kodu jest samodokumentujący, ale ostatecznie, jeśli nie rozumiesz struktury i funkcji fragmentu kodu, większość komentarzy nie pomoże. Weźmy na przykład fragment „poprawnie skomentowanego” kodu amdfan:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Ten kod jest w porządku, ale poniższe informacje są równie pouczające w większości współczesnych systemów oprogramowania i wyraźnie uznają, że zastosowanie obliczeń Newtona jest wyborem, który może zostać zmieniony, gdyby jakiś inny paradygmat fizyczny był bardziej odpowiedni:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Z mojego własnego doświadczenia wynika, że ​​bardzo mało „normalnych” sytuacji w kodowaniu, w których absolutnie potrzebujesz komentarzy. Jak często kończy się na przykład wprowadzanie własnego algorytmu? Zasadniczo wszystko inne polega na ustrukturyzowaniu systemu, aby program kodujący mógł zrozumieć stosowane struktury i wybory, które skłoniły system do korzystania z tych konkretnych struktur.

Zapominam, skąd to mam, ale:

Każdy komentarz w programie jest jak przeprosiny dla czytelnika. „Przykro mi, że mój kod jest tak nieprzejrzysty, że nie można go zrozumieć, patrząc na niego”. Musimy tylko zaakceptować fakt, że nie jesteśmy doskonali, ale starać się być doskonali i przepraszać, gdy jest to konieczne.

Przede wszystkim dobrze jest usłyszeć, że kod Twojego kolegi jest w rzeczywistości wyraźniejszy niż inny kod, który widziałeś. Oznacza to, że prawdopodobnie nie używa on „samodokumentowania” jako usprawiedliwienia dla zbyt lenistwa, aby komentować swój kod.

Kod samodokumentujący to kod, który nie wymaga komentarzy tekstowych, aby poinformowany czytelnik zrozumiał, co robi. Na przykład ten fragment kodu jest samodokumentujący:

print "Hello, World!"

i tak jest:

factorial n = product [1..n]

i tak jest:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Ta idea „świadomego czytelnika” jest bardzo subiektywna i sytuacyjna. Jeśli ty lub ktokolwiek inny ma problem z przestrzeganiem kodu kolegi, zrobiłby to dobrze, aby ponownie ocenić swój pomysł na poinformowanego czytelnika. Aby wywołać samodokumentowanie kodu, należy założyć pewien poziom znajomości używanego języka i bibliotek.

Najlepszym argumentem, jaki widziałem przy pisaniu „kodu samodokumentującego” jest to, że pozwala on uniknąć problemu, w którym komentarz tekstowy nie zgadza się z kodem podczas jego pisania. Najlepsza krytyka polega na tym, że chociaż kod potrafi opisać, co i jak robi sam, nie może wyjaśnić, dlaczego coś jest robione w określony sposób.

Kod samodokumentujący jest dobrym przykładem „OSUSZANIA” (Don't Repeat Yourself). Nie powielaj informacji w komentarzach, które są lub mogą być w samym kodzie.

Zamiast wyjaśniać, do czego używana jest zmienna, zmień nazwę zmiennej.

Zamiast wyjaśniać, co robi krótki fragment kodu, wypakuj go do metody i nadaj mu opisową nazwę (być może skróconą wersję tekstu komentarza).

Zamiast wyjaśniać, co robi skomplikowany test, wyodrębnij go również do metody i nadaj jej dobrą nazwę.

Itp.

Po tym kończy się kod, który nie wymaga tak wielu wyjaśnień, wyjaśnia się sam, więc należy usunąć komentarze, które tylko powtarzają informacje w kodzie.

Nie oznacza to, że nie masz żadnych komentarzy, jest kilka informacji, których nie możesz umieścić w kodzie, takich jak informacje o intencji („dlaczego”). W idealnym przypadku kod i komentarze uzupełniają się, dodając unikalną wartość objaśniającą bez powielania informacji.

kod samokontraktujący jest dobrą praktyką i, jeśli jest właściwie wykonany, może łatwo przekazać znaczenie kodu bez czytania zbyt wielu komentarzy. szczególnie w sytuacjach, w których domena jest dobrze rozumiana przez wszystkich w zespole.

Powiedziawszy to, komentarze mogą być bardzo pomocne dla początkujących lub testerów lub do generowania dokumentacji / plików pomocy.

samodokumentujący kod + niezbędne komentarze znacznie przyczynią się do pomocy ludziom w zespołach.

W celu:

• Kod samodokumentujący to kod, który wyraźnie wyraża swoją intencję czytelnikowi.
• Nie zupełnie. Komentarze są zawsze pomocne w komentarzach na temat tego, dlaczego wybrano daną strategię. Jednak komentarze wyjaśniające, co robi sekcja kodu, wskazują na kod, który nie jest wystarczająco samo-dokumentujący i mógłby wymagać pewnego refaktoryzacji.
• Komentarze kłamią i stają się nieaktualne. Kod zawsze mówi, że bardziej prawdopodobne jest, że powie prawdę.
• Nigdy nie widziałem przypadku, w którym treść kodu nie byłaby wystarczająco jasna bez komentarzy; jednak, jak powiedziałem wcześniej, czasem konieczne / pomocne jest dołączenie komentarza na temat przyczyny .

Należy jednak zauważyć, że kodowanie w sposób samokontraktyczny wymaga dużej dyscypliny w zakresie samodyscypliny i zespołu. Musisz nauczyć się programować bardziej deklaratywnie, musisz być bardzo pokorny i unikać „sprytnego” kodu na rzecz kodu, który jest tak oczywisty, że wydaje się, że każdy mógł go napisać.

Kiedy czytasz „samodokumentujący się kod”, widzisz, co on robi, ale nie zawsze możesz zgadnąć, dlaczego robi to w ten konkretny sposób.

Istnieje mnóstwo ograniczeń niezwiązanych z programowaniem, takich jak logika biznesowa, bezpieczeństwo, wymagania użytkowników itp.

Kiedy przeprowadzasz konserwację, te informacje backgorund stają się bardzo ważne.

Tylko moja szczypta soli ...

Po pierwsze, rozważ następujący fragment:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

W tym przykładzie masz 5 wierszy komentarzy na 3 wiersze kodu. Co gorsza - komentarze nie dodają niczego, czego nie można zobaczyć po przeczytaniu kodu. Jeśli masz 10 takich metod, możesz uzyskać „ślepotę na komentarze” i nie zauważyć jednej metody, która odbiega od wzorca.

Jeśli oczywiście lepsza wersja byłaby:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Jednak w przypadku trywialnego kodu wolę nie mieć komentarzy. Cel i ogólną organizację lepiej wyjaśniono w osobnym dokumencie poza kodem.

Różnica polega na „co” i „jak”.

• Powinieneś udokumentować „co” robi rutyna.
• Nie powinieneś dokumentować „jak” to robi, chyba że specjalne przypadki (np. Odnoszą się do konkretnego dokumentu algorytmu). To powinno być udokumentowane.

Jedną rzeczą, na którą powinieneś zwrócić uwagę swojemu współpracownikowi, jest to, że bez względu na to, jak samok dokumentuje swój kod, jeśli rozważone zostaną inne alternatywne podejścia i odrzucone, informacje zostaną utracone, chyba że skomentuje kod tymi informacjami. Czasami równie ważne jest, aby wiedzieć, że rozważano alternatywę i dlaczego została ona odrzucona, a komentarze do kodu najprawdopodobniej przetrwają z czasem.

W firmie, w której pracowałem, jeden z programistów przykleił następujące elementy na górze swojego monitora.

„Dokumentuj swój kod, tak jak osoba, która go utrzymuje, jest zabójczym maniakiem, który wie, gdzie mieszkasz”.

kod samo-dokumentujący zwykle używa nazw zmiennych dokładnie pasujących do tego, co robi kod, dzięki czemu łatwo jest zrozumieć, co się dzieje

Jednak taki „samodokumentujący kod” nigdy nie zastąpi komentarzy. Czasami kod jest po prostu zbyt skomplikowany, a samodokumentujący kod nie wystarcza, szczególnie w zakresie łatwości konserwacji.

Kiedyś miałem profesora, który mocno wierzył w tę teorię. Właściwie najlepszą rzeczą, jaką pamiętam, było to, że „Komentarze są dla maminsynek”
Z początku zaskoczyło nas wszystkich, ale ma to sens.
Sytuacja jest jednak taka, że ​​nawet jeśli możesz zrozumieć, co się dzieje w kodzie, ale ktoś mniej doświadczony, że możesz za nim pójść i nie zrozumieć, co się dzieje. To wtedy komentarze stają się ważne. Wiem wiele razy, że nie wierzymy, że są ważne, ale jest bardzo niewiele przypadków, w których komentarze są zbędne.

Dziwi mnie, że nikt nie przyniósł „ Literate Programming ”, techniki opracowanej w 1981 roku przez Donalda E. Knutha z TeX i sławy „The Art of Computer Programming”.

Założenie jest proste: skoro kod musi być zrozumiany przez człowieka, a kompilator po prostu wyrzuca komentarze, dlaczego nie dać każdemu tego, czego potrzebuje - pełny tekstowy opis zamiaru kodu, nieskrępowany wymaganiami języka programowania , dla czytelnika i czysty kod dla kompilatora.

Narzędzia do programowania piśmiennego wykonują to poprzez specjalne oznakowanie dokumentu, który informuje narzędzia, która część powinna być źródłem, a co tekstem. Następnie program wyrywa części kodu źródłowego z dokumentu i składa plik kodu.

Znalazłem przykład w Internecie: http://moonflare.com/code/select/select.nw lub wersję HTML http://moonflare.com/code/select/select.html

Jeśli znajdziesz w niej książkę Knutha w bibliotece (Donald E. Knuth, Literate Programming, Stanford, Kalifornia: Center for Study of Language and Information, 1992, CSLI Lecture Notes, no. 27.), powinieneś ją przeczytać.

To jest samodokumentujący się kod, wraz z uzasadnieniem i wszystkim innym. Nawet tworzy fajny dokument, wszystko inne to tylko dobrze napisane komentarze :-)

Chciałbym zaoferować jeszcze jedną perspektywę dla wielu ważnych odpowiedzi:

Co to jest kod źródłowy? Co to jest język programowania?

Maszyny nie potrzebują kodu źródłowego. Są zadowoleni z uruchomienia zespołu. Języki programowania są dla naszej korzyści. Nie chcemy pisać asemblera. Musimy zrozumieć, co piszemy. Programowanie polega na pisaniu kodu.

Czy powinieneś być w stanie przeczytać to, co piszesz?

Kod źródłowy nie jest napisany w ludzkim języku. Zostało wypróbowane (na przykład FORTRAN), ale nie jest całkowicie skuteczne.

Kod źródłowy nie może być niejednoznaczny. Dlatego musimy włożyć w to więcej struktury niż w przypadku tekstu. Tekst działa tylko z kontekstem, który przyjmujemy za pewnik, gdy używamy tekstu. Kontekst w kodzie źródłowym jest zawsze jawny. Pomyśl „za pomocą” w C #.

Większość języków programowania ma nadmiarowość, dzięki czemu kompilator może nas złapać, gdy nie jesteśmy spójni. Inne języki używają więcej wnioskowania i starają się wyeliminować tę nadmiarowość.

Nazwy typów, nazwy metod i nazwy zmiennych nie są potrzebne komputerom. Są one wykorzystywane przez nas do odniesienia. Kompilator nie rozumie semantyki, którą możemy wykorzystać.

Języki programowania są językowym pomostem między człowiekiem a maszyną. Musi być dla nas zapisywalny i czytelny dla nich. Drugorzędne wymagania to, aby był on dla nas czytelny. Jeśli jesteśmy dobrzy w semantyce tam, gdzie jest to dozwolone i dobrze w tworzeniu kodu, kod źródłowy powinien być łatwy do odczytania nawet dla nas. Najlepszy kod nie wymaga komentarzy.

Ale w każdym projekcie czai się złożoność, zawsze musisz zdecydować, gdzie umieścić złożoność i które wielbłądy połknąć. To są miejsca, w których można używać komentarzy.

Kod samodokumentujący jest łatwym rozwiązaniem problemu, który z biegiem czasu zmienia się w kodzie, komentarzach i dokumentacji. I jest to czynnik dyscyplinujący, aby pisać czysty kod (jeśli jesteś tak surowy wobec siebie).

Dla mnie są to zasady, których staram się przestrzegać:

• Kod powinien być tak łatwy i czytelny, jak to możliwe.
• Komentarze powinny zawierać uzasadnienie podjętych przeze mnie decyzji projektowych, na przykład: dlaczego korzystam z tego algorytmu lub ograniczenia, jakie ma kod, takie jak: nie działa, gdy ... (należy to załatwić w umowie / stwierdzeniu w kodzie) (zwykle w ramach funkcji / procedury).
• Dokumentacja powinna zawierać listę użycia (wywoływanie konwersji), efektów ubocznych, możliwych wartości zwracanych. Można go wyodrębnić z kodu za pomocą narzędzi takich jak jDoc lub xmlDoc. Dlatego zwykle znajduje się poza funkcją / procedurą, ale jest bliskie opisanemu kodowi.

Oznacza to, że wszystkie trzy sposoby dokumentowania kodu żyją blisko siebie i dlatego są bardziej prawdopodobne, że zostaną zmienione, gdy kod się zmieni, ale nie nakładają się na to, co wyrażają.

Prawdziwym problemem z tak zwanym kodem samokontrującym jest to, że przekazuje to, co faktycznie robi. Chociaż niektóre komentarze mogą pomóc komuś lepiej zrozumieć kod (np. Kroki algorytmów itp.), Są one do pewnego stopnia zbędne i wątpię, byś przekonał swojego partnera.

Jednak naprawdę ważne w dokumentacji są rzeczy, które nie są bezpośrednio widoczne w kodzie: podstawowe zamiary, założenia, wpływy, ograniczenia itp.

Możliwość szybkiego sprawdzenia, czy kod wykonuje X, jest o wiele łatwiejsza niż ustalenie, że kod nie robi Y. Musi udokumentować Y ...

Możesz pokazać mu przykład kodu, który wygląda dobrze, jest oczywisty, ale tak naprawdę nie obejmuje na przykład wszystkich podstaw danych wejściowych i sprawdza, czy go znajdzie.

Myślę, że kod samodokumentujący jest dobrym zamiennikiem komentarzy. Jeśli potrzebujesz komentarzy wyjaśniających, jak i dlaczego kod jest taki, jaki masz, to masz nazwy funkcji lub zmiennych, które należy zmodyfikować, aby były bardziej objaśniające. Koder może zdecydować, czy uzupełni niedobór komentarzem, czy zmieniając nazwy niektórych zmiennych i funkcji oraz kod refaktoryzujący.

Jednak tak naprawdę nie może zastąpić twojej dokumentacji, ponieważ dokumentacja jest tym, co dajesz innym, aby wyjaśnić, jak korzystać z twojego systemu, a nie jak to robi.

Edycja: Ja (i prawdopodobnie wszyscy inni) powinienem prawdopodobnie przewidzieć, że aplikacja DSP powinna być bardzo dobrze skomentowana. Dzieje się tak głównie dlatego, że aplikacje DSP są w zasadzie 2 dla pętli zasilanych tablicami wartości i dodaje / zwielokrotnia / itd. Wspomniane wartości ... aby zmienić program, zmień wartości w jednej z tablic ... potrzebuje kilku komentarzy, aby powiedzieć, co robisz w takim przypadku;)

Kiedy piszę kod matematyczny, czasem przydaje mi się pisanie długich komentarzy przypominających esej, wyjaśniających matematykę, konwencje notacyjne, których używa kod, i to, jak wszystko do siebie pasuje. Mówimy tutaj o setkach linii dokumentacji.

Staram się, aby mój kod był tak samo dokumentujący, jak to możliwe, ale kiedy wrócę do pracy nad nim po kilku miesiącach, naprawdę muszę przeczytać wyjaśnienie, aby nie robić z niego haszu.

Oczywiście ten rodzaj ekstremalnych środków nie jest konieczny w większości przypadków. Myślę, że morał tej historii jest taki: inny kod wymaga różnej ilości dokumentacji. Część kodu można napisać tak wyraźnie, że nie potrzebuje komentarzy - więc napisz go wyraźnie i nie używaj tam komentarzy!

Ale wiele kodu wymaga komentarzy, aby mieć sens, więc napisz go tak wyraźnie, jak to możliwe, a następnie użyj tyle komentarzy, ile potrzeba ...

Twierdziłbym - jak wielu z was - że aby być naprawdę samok dokumentującym, kod musi wykazywać jakąś formę intencji. Ale jestem zaskoczony, że nikt jeszcze nie wspominał o BDD - Behaviour Driven Development . Częścią tego pomysłu jest to, że masz zautomatyzowane testy (kod) wyjaśniające cel twojego kodu, co jest tak trudne do wyjaśnienia inaczej.

Dobre modelowanie domen 
+ dobre nazwy (zmienne, metody, klasy) 
+ przykłady kodu (testy jednostkowe z przypadków użycia) 
= oprogramowanie do samodzielnego dokumentowania 

Kilka powodów, dla których dodatkowe komentarze oprócz kodu mogą być wyraźniejsze:

• Kod, na który patrzysz, został wygenerowany automatycznie, dlatego wszelkie zmiany w kodzie mogą zostać zablokowane przy następnym kompilowaniu projektu
• Niezbyt prosta implementacja została wymieniona na zwiększenie wydajności (rozwijanie pętli, tworzenie tabeli odnośników do kosztownej kalkulacji itp.)

Będzie to wszystko, co zespół ceni w swojej dokumentacji. Sugerowałbym, że dokumentowanie dlaczego / zamiary zamiast jak jest ważne i nie zawsze jest to ujmowane w kodzie samok dokumentującym. get / set no te są oczywiste - ale obliczenia, pobieranie itp. coś z tego, co powinno być wyrażone.

Pamiętaj także o różnicach w swoim zespole, jeśli pochodzisz z różnych narodowości. Różnice w dykcji mogą wpływać na nazewnictwo metod:

BisectionSearch

BinarySearch

BinaryChop

Te trzy metody opracowane przez programistów przeszkolonych na 3 różnych kontynentach robią to samo. Jedynie czytając komentarze opisujące algorytm, byliśmy w stanie zidentyfikować duplikację w naszej bibliotece.

Dla mnie czytanie kodu, który wymaga komentarza, jest jak czytanie tekstu w języku, którego nie znam. Widzę oświadczenie i nie rozumiem, co robi ani dlaczego - i muszę patrzeć na komentarze. Czytam zdanie i muszę poszukać w słowniku, aby zrozumieć, co to znaczy.

Zazwyczaj łatwo jest napisać kod, który sam dokumentuje to, co robi. Aby powiedzieć, dlaczego tak się dzieje, komentarze są bardziej odpowiednie, ale nawet tutaj kod może być lepszy. Jeśli rozumiesz swój system na każdym poziomie abstrakcji, powinieneś spróbować uporządkować swój kod w podobny sposób

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Gdzie nazwa metody odzwierciedla twoje zamiary, a treść metody wyjaśnia, w jaki sposób osiągasz swój cel. W każdym razie nie możesz powiedzieć całej książki w tytule, więc główne abstrakcje twojego systemu wciąż muszą zostać udokumentowane, a także złożone algorytmy, nietrywialne kontrakty metod i artefakty.

Jeśli kod, który produkuje twój kolega, jest naprawdę samowydokumentowany - na szczęście ty i on. Jeśli uważasz, że kod Twojego kolegi wymaga komentarza - on potrzebuje. Po prostu otwórz najbardziej nietrywialne miejsce w nim, przeczytaj je raz i sprawdź, czy wszystko zrozumiałeś. Jeśli kod jest samokumentowany - powinieneś. Jeśli nie - zadaj swojemu koledze pytanie na ten temat, po tym, jak udzieli odpowiedzi, zapytaj, dlaczego ta odpowiedź nie została wcześniej udokumentowana w komentarzach lub kodzie. Może twierdzić, że kod jest samodokumentem dla takiej inteligentnej osoby jak on, ale i tak musi szanować innych członków zespołu - jeśli twoje zadania wymagają zrozumienia jego kodu, a jego kod nie wyjaśnia ci wszystkiego, co musisz zrozumieć - potrzebuje komentarze

Większość dokumentacji / komentarzy służy przyszłym ulepszeniom / programistom kodu, a tym samym umożliwia utrzymanie kodu. Najczęściej wracamy do naszego modułu później, aby dodać nowe funkcje lub zoptymalizować. Wówczas łatwiej byłoby zrozumieć kod, po prostu czytając komentarze niż przechodząc przez liczne punkty przerwania. Poza tym wolałbym spędzać czas na zastanawianiu się nad nową logiką niż na rozszyfrowaniu istniejącej.

Myślę, że może dojść do tego, że jeśli komentarze wyjaśniają, co robi kod, należy go ponownie napisać, aby wyjaśnić, co to jest. To właśnie ma na myśli przez samodokumentowanie kodu. Często może to oznaczać po prostu rozbicie długiej funkcji na logiczne mniejsze części z opisową nazwą funkcji.

To nie znaczy, że kod nie powinien być komentowany. Oznacza to, że komentarze powinny podawać powód, dla którego kod został napisany w ten sposób.

Uważam, że zawsze powinieneś dążyć do uzyskania samodokumentującego się kodu, ponieważ ułatwia on czytanie kodu. Jednak trzeba też być pragmatycznym w sprawach.

Na przykład zazwyczaj dodaję komentarz do każdego członka klasy (do tego używam komentarzy do dokumentacji). Opisuje to, co powinien zrobić członek, ale nie sposób, w jaki to robi. Przekonałem się, że kiedy czytam kod, szczególnie stary kod, pomaga mi to szybko zapamiętać, do czego służy element członkowski, a także łatwiejsze niż czytanie kodu i opracowywanie go, szczególnie jeśli przepływ kodu przeskakuje dość .

To tylko moja opinia. Znam wielu ludzi, którzy w ogóle pracują bez komentarzy i twierdzą, że nie stanowi to problemu. Zapytałem jednak kogoś o metodę, którą napisali sześć miesięcy wcześniej i przez kilka minut musiałem pomyśleć, aby powiedzieć mi dokładnie, co to zrobiło. Nie stanowi to problemu, jeśli metoda jest komentowana.

Na koniec należy pamiętać, że komentarze są tak samo częścią systemu, jak kod. Podczas refaktoryzacji i zmiany funkcjonalności musisz również zaktualizować swoje komentarze. Jest to jeden argument przeciwko używaniu komentarzy, ponieważ są one gorsze niż bezużyteczne, jeśli są niepoprawne.