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


258

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.


118
Wiesz, co naprawdę robi na mnie wrażenie? Nie zgadzasz się z tym facetem, ale prosisz go zrozumieć <i> go </i>, a nie o więcej amunicji przeciwko niemu.
kajaco

14
Jako opowieść o skrajnie odwrotnym przypadku mam współpracownika, który pisze tony dokumentacji: w każdym pliku CPP zawiera instrukcję z co najmniej kilkadziesiąt stronami na temat implementacji i korzystania z udostępnionych funkcji. Pisze jednak katastrofalnie długie i skomplikowane funkcje (pojedyncze funkcje z 8000 wierszami kodu), sprzeczne z intuicją identyfikatory zmiennych i funkcji itp. W porównaniu z nią zabrałbym kogoś, kto próbowałby napisać samodokumentujący się kod, który zwalnia komentuje każdego dnia, pod warunkiem, że jego kod jest dobrze zorganizowany i ma małe, łatwe do zrozumienia funkcje.
stinky472


1
Krótko mówiąc, można uniknąć większości komentarzy wyjaśniających, jak działa kod i samodokumentować kod w tym zakresie. Ale często wymagane jest również wyjaśnienie, dlaczego kod działa w ten sposób, np. Gdy omija się ograniczenia w bibliotece. Zwykle potrzebujesz komentarzy, aby wyjaśnić dlaczego.
Lutz Prechelt

2
Pracowałem z kimś, kto wszystko przesadził, ale zwykle z bezużytecznymi komentarzami, na przykład i++; // increment i- ale bez wyjaśnienia, dlaczego i należy zwiększać w tym momencie funkcji.
nnnnnn

Odpowiedzi:


177

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.


Myślę, że zgodnie z tą odpowiedzią: memeagora.blogspot.com/2008/11/comments-code-smell.html
Maslow

14
Punkt nr. 3 powinien być częścią punktu nr. 1 IMHO, jeśli metoda jest tak złożona, że ​​wymaga komentarzy o dużej abstrakcji dla kilku bloków kodu, każdy taki blok kodu powinien być nową metodą.
Bjarke Freund-Hansen

10
+1 dla „nie oznacza, że ​​nie powinno być komentarzy”, co wydaje się być opinią niektórych osób.
Skurmedel

4
Nadal nie trzeba komentować, że: public static Collection <File> filesGreaterThan (ścieżka pliku, int sizeInBytes);
Trylks

6
Dobrą zasadą jest dla mnie, że komentarze nigdy nie powinny wyjaśniać, CO robi kod, ale mogą być użyte do wyjaśnienia, DLACZEGO to robi. Innymi słowy, skomentuj blok kodu, aby wyjaśnić, dlaczego on istnieje, a nie jak to działa. Jeśli potrafisz rozdzielić blok na jego własną, jednoznacznie nazwaną metodę, to jest to jeszcze lepsze. O to właśnie chodzi w kodzie samodokumentującym.
Mel.

387

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


73
Cała ta część powinna jednak naprawdę mieć opisową nazwę;)
workmad3

7
Tak, łatwiej byłoby mi odczytać funkcję displacementDueToGravity (int timeInSeconds, float gravitationalAcceleration = 9,81).
Cristián Romo

18
Jedyny komentarz, za którym tęsknię, to: dlaczego 5 sekund?
John Nilsson,

3
Kolejny głos na opisową nazwę funkcji. Nie podaje samego równania, ale nie widzę, aby było to potrzebne.
Loren Pechtel

18
Jakie są jednostki siły grawitacji? Istnieją ograniczenia dotyczące dodawania do nazwy zmiennej. W pewnym momencie musisz wyjaśnić, co próbujesz zrobić . Często nie jest to oczywiste , dlatego musisz komentować kod. Absolutnie marnotrawstwem jest twierdzenie, że kod jest samodokumentujący, a jedynie opisowy .
Nick

172

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!


Zgoda. Chociaż czasami nawet najlepszy kod może ukryć jego końcowy efekt, można to zrobić, odpowiadając na pytanie dlaczego w komentarzach. Jak w „Dlaczego właśnie zmieniłeś te 5 zmiennych w ten sposób?”
Sam Erwin,

Moje 2 centy: czy przypadek [Unit, Spec, Behavior,] nie jest odpowiedzią na pytanie „dlaczego na ziemi”? Następnie możesz przeczytać przypadek testowy i powinieneś wiedzieć, dlaczego.
Jonke

2
Myślę, że mogą one odpowiedzieć na pytanie dlaczego, ale nie wyjaśniają takich rzeczy, jak: „Wypełniam tę strukturę tak wieloma bajtami, aby pozostała właściwie wyrównana po przesłaniu na jakąś niejasną platformę”. Dla nich komentarze do kodu są najlepszym sposobem na zachowanie wiedzy instytucjonalnej.
tsellon

Dlatego powinieneś komentować tam, gdzie intencja nie jest jednoznaczna, biorąc pod uwagę sam kod.
Draemon

2
@tsellon, twoja zautomatyzowana specyfikacja może ci to powiedzieć, i fajną rzeczą jest to, że kod sprawdza kod implementacyjny. Więc jeśli implementacja jakoś się zmieni, specyfikacja się psuje. Jakie to miłe? Komentarze, które ostrzegają, gdy kod implementacyjny nie robi już tego, co podano w komentarzu?
Pragmatic Agilist,

96

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.


28
To, co wydaje się trywialne, aby zrozumieć w momencie pisania kodu, może w rzeczywistości być bardzo trudne do zrozumienia dla kogoś innego, nawet jeśli ta osoba jest w rzeczywistości sobą za kilka miesięcy / lat.
Anders Sandvig

15
Często uważam, że rzeczy, które napisałem w piątek, są trudne do odczytania w poniedziałek rano :)
Loofer,

1
co prowadzi nas do „staraj się nie pisać komentarzy”
mustafabar

37

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.


1
IMHO Blok powinien powiedzieć, jak , nazwa funkcji powinna powiedzieć, dlaczego . Tak długo, jak używasz ich obu razem, przekazujesz zarówno zamiar, jak i wdrożenie .... int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}...
Podstawowy

19

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.


2
potrzebujesz więcej głosów pozytywnych, twój przykład wyjaśnia, dlaczego powinniśmy używać nazw funkcji do dokumentowania intencji.
Ape-inago

16

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.


26
Śmieci. Dobre komentarze w kodzie absolutnie mają swoje miejsce. Weźmy przykład wyboru między dwiema równie poprawnymi metodami rozwiązania problemu. Komentarz wyjaśniający, dlaczego jedna metoda została wybrana w stosunku do drugiej, ma ogromne znaczenie i nigdy nie można uzyskać tego z samego kodu.
Scott Dorman

7
Jeśli istnieją dwie WIELKIE PRAWIDŁOWE metody, to czy ma znaczenie, dlaczego wybrałeś jedną z nich?
EBGreen,

1
Tak, równie poprawne nie oznacza dokładnie tego samego. Jedna metoda może być szybsza w niektórych sytuacjach niż inna.
Ikke

Zatem jeśli twoim kryterium decyzyjnym jest szybkość, nie są W PRAWIDŁOWO PRAWIDŁOWE. Nie twierdzę, że komentarze są złe. Tylko, że są one wymagane, ponieważ obecnie nie ma języka programowania, który byłby tak jednoznaczny i jednoznaczny, że każdy mógłby spojrzeć na kod i natychmiast poznać jego intencje.
EBGreen,

9
Nie sądzę, żeby ludzie rozumieli ten cytat tak samo jak ja. Rozumiem, że powinieneś starać się zawsze pisać kod, który jest tak jasny, że nie trzeba go komentować, ale musisz zaakceptować fakt, że jest to ideał, który nigdy nie działa w rzeczywistości.
EBGreen,

14

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.


14

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.


4
Jeden wyjątek: źli programiści. Widziałem komentarze mówiące, że kod robi coś, co nie jest. Następnie zadaję sobie pytanie: czy powinienem naprawić kod lub komentarz?
Guge

Nie możesz pokonać nazw metod w Objective-C. :)

13

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.


9

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


Dodam tutaj nit nit. Kod nie zawsze „mówi prawdę”. Kod może wprowadzać w błąd i bardzo łatwo zaciemniać jego intencje. Na przykład źle nazwana zmienna lub metoda może kłamać tak samo jak nieaktualny komentarz.
Wedge

Nazwy metod mogą kłamać i mogą być również nieaktualne.
Calmarius

7

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


6

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.


Dokumentowanie osób pobierających i ustawiających może wydawać się trywialne, ale myślę, że istnieje przyjemny środek między niepotrzebnym komentarzem a brakiem komentarza. Istotą komentarzy Javadoc jest poinformowanie kogoś, kto nie może lub nie ma ochoty przyjrzeć się kodowi w metodzie.
James McMahon

6

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.

Kategorycznie się nie zgadzam. To, co robi rutyna, powinno wynikać z nazwy. Jak to powinno być oczywiste z kodu implementacyjnego. Dlaczego implementacja została napisana tak, jak jest, powinna zostać udokumentowana .
Anthony Manning-Franklin,

5

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.


Przyjmujesz to z reguły i kończysz pisanie podręcznika w swojej bazie kodu ;-) Zgadzam się jednak na nieoczywiste decyzje.
ddimitrov

@ddimitrov, to dobra obserwacja. Ale jak mówisz w przypadku nieoczywistych decyzji (i zwykle są to te, które naprawdę wymagają dokumentacji), jest to dobra praktyka.
Onorio Catenacci

Dokumentuj kod, który nie został napisany! :)
Tony

5

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


4

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.


Następnie refaktoryzuj go, aż będzie wyraźniejszy. Jestem głęboko przekonany, że kod nie może powiedzieć nic dość wyraźnie.
Tigraine

4
Z wyjątkiem tego, dlaczego wybraną konkretną implementację, algorytm lub formułę wybrano zamiast innej równie poprawnej. Nigdy nie możesz opisać, dlaczego dokonano wyboru w kodzie, tylko jaki był ten wybór.
Scott Dorman

1
@ scott: możesz umieścić obie opcje w większej klasie, a drugą pozostawić bez komentarza o ... och, czekaj.
Ape-inago

4

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


Jest to w rzeczywistości przeciwieństwo kodu samodokumentującego. Tekst dla człowieka, kod dla maszyny. A jakim językiem powinien być kod? Oczywiście montaż. Ludzie nie muszą tego czytać, prawda? Muszą tylko to napisać!
Guge

4

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.


3

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


3

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.


3

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


Czyli nazwa funkcji lub zmiennej zapewni wystarczająco trywialnie jasny kontekst, aby wyjaśnić, dlaczego wybrano jedną implementację zamiast innej, biorąc pod uwagę dwa lub więcej równie poprawnych sposobów rozwiązania problemu?
Scott Dorman

3

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


3

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 

2

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

2

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.


2

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


2

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.


1

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.


1

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.

Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.