Dokumentowanie kodu źródłowego

2

Ja dokumentuje niemal każdą linijkę kodu i to bardzo opisowo. Kiedy później np. po roku-dwóch wracam do kodu, pracuje się komfortowo vs sytuacja gdzie mamy ciurkiem kod bez żadnych wyjaśnień, i trzeba wszystko analizować.

W sytuacji kiedy produkuję dziennie po kilka tysięcy linii, nie wyobrażam sobie robienia tego w inny sposób. Wiadomo, że są schematy, nazewnictwo funkcji i zmiennych, znana struktura, etc. jednak komentarze znacznie przyspieszają poprawki w starym kodzie.

Wg. mnie warto trochę się zatrzymać, i poświęcić czas na komentarze - i to nie tylko dla czytania później, ale w trakcie do wyjaśniania samemu sobie co ja robię, taki loopback w umyśle dodatkowo dbający o jakość kodu.

Co więcej, komentując nad linią i robiąc odstęp powyżej komentarza i poniżej linii, kod staje się naturalnie bardziej przejrzysty.

0

@AnyKtokolwiek:
Zapytałem ogólnie czy jest sens tworzyć komentarze dokumentacyjne. Kontekst ogólny, dowolna technologia, po prostu robię projekt i zastanawiam się, czy opisać każdą klasę, metodę, parametr metody, interfejs...

Pierwszy lepszy przykład z Javy, bo dla C# nie potrafiłem znaleźć fajnego odpowiednika.

/**
* Returns an Image object that can then be painted on the screen. 
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument. 
* <p>
* This method always returns immediately, whether or not the 
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives 
* that draw the image will incrementally paint on the screen. 
*
* @param  url  an absolute URL giving the base location of the image
* @param  name the location of the image, relative to the url argument
* @return      the image at the specified URL
* @see         Image
*/
public Image getImage(URL url, String name) {
    try {
        return getImage(new URL(url, name));
    } catch (MalformedURLException e) {
        return null;
    }
}

Bardziej rozbudowany przykład
https://github.com/openjdk/jd[...]/classes/java/io/Console.java

7

Komentarze są bardzo ważne.

6

Szczerze jeszcze nigdy nie zdarzyło mi się trafić na przydatny komentarz. Szybciej dotrę co się dzieje czytając kod niż komentarz. Opis argumentów metody to co innego, zwłaszcza w publicznej bibliotece wręcz niezbędne; nie za każdym razem zaglądam do dokumentacji, fajnie jak w takim opisie jest przykład użycia jeśli nie jest jasny i skrajne zachowania.
Tak więc jestem za opisywaniem funkcji / metod, ale przeciw komentowaniu każdej linii kodu - dobre nazewnictwo i krótkie funkcje robiące tylko to co sugeruje nazwa wystarczają. Komentarze w kodzie używam tylko jeśli coś jest naprawdę dziwne, jest użyty jakiś workaround albo api z którego się korzysta ma nieoczywiste efekty uboczne.
No i odczywistą dokumentację typu:

 @param  name   name of sth
 @param  age   age
 @return      result

można sobie odpuścić, a niestety bardzo często coś takiego widuję

Komentarze za to się czasami przydają jako zakładki - przykładowo w kodzie obecnego projektu ktoś dodał komentarz "dla Marka" - nie mam pojęcia o co chodzi i jakiego Marka, ale ten komentarz jest o 10 linii od bardzo przydatnego do debugowania miejscu i często go wyszukuję, bo nie pamiętam nazwy klasy, ani metod, za to pamiętam ten komentarz :)

Kiedyś słyszałem że zwolnili chłopa za nieczytelny kod - niestety odmówił komentarza

3

Faktycznie na frontendach JS+HTML bardzo rzadko mam jakieś komentarze bo nie ma co komentować przerzucania danych z lewa w prawo i każdy i tak siadając do takiego kodu ogólnie wie co się w nim dzieje i czego się spodziewać. Jednak w backendach gdzie mamy już głębszą styczność z logiką biznesową to czasem nawet krótki komentarz ręczny jest niezbędny.

Dla mnie podstawą są zwykłe komentarze opisujące co robi dany moduł lub funkcja oczywiście w zależności od jej złożoności. Systemy komentowania zapewne ułatwiają poruszanie się po IDE i samym kodzie ale ogólnej idei biznesowej już ze sobą nie niosą i jak po 8 latach siadamy do kodu nie pamiętając logiki biznesowej to jest klapa.
Także samodokumentujący się kod to wg mnie mrzonka... Chyba, że mówimy o jakiś banałach. W tym co robię większość rzeczy ociera się o specjalistyczną wiedzę i bez odpowiedniego komentarza kodu zwyczajnie nie da się zrozumieć, a samo zrozumienie poszczególnych funkcji i tak daje niewiele.
Przykładowo jeśli masz np. funkcję obliczającą jakąś składkę z zaokrąglaniem do pełnych 5zł to bez odpowiedniego komentarza taką funkcję można potraktować jako błąd. Wg mnie komentarz uzasadniający jej zachowanie jest niezbędny.
Natomiast w miejscach, w których zostały wykonane głębsze nieintuicyjne optymalizacje taki komentarz jest już obowiązkowy.

3

W przypadku biblioteki zewnętrznej, nad którą nie pracuję, dobra dokumentacja to podstawa. Jeśli chodzi o dokumentację kodu, nad którym pracuję, jeszcze chyba nie zdarzyło mi się pracować w projekcie, który posiadałby sensowną dokumentację. Tylko czytanie kodu+RE ;)

Co do kodu który piszę, raczej nie piszę komentarzy (z wyjątkiem sytuacji kiedy mamy coś co trudno wyrazić kodem). Raczej stawiam na małe samodzielne kawałki kodu, które można w miarę łatwo ogarnąć. Nie ma nic gorszego niż kilka tysięcy linii wzajemnie powiązanych zmiennych i wywołań funkcji (no chyba że kilkadziesiąt tysięcy powiązanych zmiennych, wywołań i goto). Wywołanie funkcji/metody powinno być jedynym sposobem wyrażenia zależności miedzy takimi kawałkami kodu. Wtedy jakoś idzie dojść co z czym się wiąże.

5

@revenger:

No co Ty, pogieło CIę? Jak udokumentujesz, to Cię zwolnią i na Twoje miejsce zatrudnią skończoną ilość studentów, bo będzie wiadomo o co chodzi w tym kodzie. Do emerytury daleko, a te młode Cię zaraz wygryzą.

5
katakrowa napisał(a):

Także samodokumentujący się kod to wg mnie mrzonka... Chyba, że mówimy o jakiś banałach. W tym co robię większość rzeczy ociera się o specjalistyczną wiedzę i bez odpowiedniego komentarza kodu zwyczajnie nie da się zrozumieć, a samo zrozumienie poszczególnych funkcji i tak daje niewiele.

Pracowałem przy projektach ze złożoną logiką biznesową i nigdy nie było takiej potrzeby, ewentualnie odniesienie do jiry która dokumentuje dokładnie zachowanie - komentarze w kodzie raczej czegoś takiego i tak nie zastąpią bo mowa o wielu dokumentach z diagramami, odtwarzanie takiej wiedzy z komentarzy w kodzie jest raczej daremne. Zresztą i to jest raczej często zbędne bo gdy jakaś logika jest niejasna to zazwyczaj wystarczy blame i wyciągnięcie jiry z treści commita. Zazwyczaj konkretną logiką zajmuje się konkretna klasa i jej zachowanie jest opisane w opisie klasy, nie ma potrzeby komentować poszczególnych linii kodu.

Przykładowo jeśli masz np. funkcję obliczającą jakąś składkę z zaokrąglaniem do pełnych 5zł to bez odpowiedniego komentarza taką funkcję można potraktować jako błąd. Wg mnie komentarz uzasadniający jej zachowanie jest niezbędny.

W podanym przykładzie funkcja może po prostu zaokrąglać, a "5" byłoby jej argumentem więc nikt nie potraktowałby czegoś takiego jako błąd, a komentarz jest zbędny. Ewentualnie nazwa funkcji może mówić że zaokrągla do pełnych piątek. Jeśli funkcja nazywa się "round" i zaokrągla domyślnie w ten sposób to rzeczywiście wtf, nawet z komentarzem w kodzie. Masz jakiś inny przykład?

“It should be noted that no ethically -trained software engineer would ever consent to write a DestroyBaghdad procedure.
Basic professional ethics would instead require him to write a DestroyCity procedure, to which Baghdad could be given as a parameter.”

― Nathaniel S. Borenstein

3

Tak przy okazji dzielenie kodu na małe kawałki / klocki zamiast monolitu oczywiście jest jak najbardziej pożądane, tylko nie bardzo zastępuje komentowanie, jak ktoś wyżej napisał.

Otóż nawet jeżeli podzieli się kod na jak najmniejsze logicznie części, to później mamy odwołania do tych części, które też wymagają komentarza.

Samo wyjaśniające się nazewnictwo zmiennych, klas, metod nie jest w stanie zawsze zastąpić komentarzy.

Co więcej komentowanie ułatwia też później zautomatyzowane budowanie dokumentacji API.

3

hacki w kodzie wypadałoby komentować

1 użytkowników online, w tym zalogowanych: 0, gości: 1, botów: 0