[Viters]

#programowanie #cpp
Hej, mam pytanie odnośnie konwencji komentowania. Mam czysto wirtualną klasę nadrzędną z zaimplementowanymi niektórymi metodami. Potem są klasy, które po niej dziedziczą implementując pozostałe potrzebne metody i dorzucając własne. Jak w tym momencie się powinno komentować deklaracje metod? Na razie mam tak, że klasa nadrzędna ma skomentowane wszystkie metody, a w klasach podrzędnych mam po prostu skopiowane komentarze z nadrzędnej + ewentualne metody, które należą tylko do klasy podrzędnej. Zastanawiam się, czy powielanie komentarzy to dobry pomysł od strony ewentualnego czytelnika kodu (dodatkowe zajęte miejsce kontra brak potrzeby szukania komentarzy w klasie nadrzędnej).

[f.....6]

@Viters: jeżeli musisz komentować każdą funkcję to źle do tego podchodzisz. Kod ma być samokomentujący, a wszelkie dopiski występować tylko przy nieoczywistych liniach - czyli im rzadziej tym lepiej.

[Viters]

@frogi16: Nie rozumiem. Z tego co kojarzę to w deklaracji klasy każda metoda powinna być udokumentowana.

[f.....6]

@Viters: to komentuj string getName(), proszę bardzo.

[Viters]

@frogi16: Cytując Paula de Vrieze:

For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter

/**
* Get the current value of the foo property.
* The foo property controls the initial guess used by the bla algorithm in
* {@link #bla}
* @return The initial guess used by {@link #bla}
*/
int getFoo() {
return

[b.....4]

@Viters: pisanie komentarzy to w ogóle zły pomysł. Polecam CleanCode o ile coś takiego istnieje w C++, jak tam macie nazwy typu strokptrdupa, &kutasomg ( ͡° ͜ʖ ͡°)

[f.....6]

@Viters: a cytat Roberta Martina masz w załączniku. I czego to dowodzi? W założeniach komentowanie może brzmieć interesująco, ale takie nie jest. Jeżeli chcesz to komentuj wszystko, ale to ma sens tylko dopóki twoje projekty nie przekraczają paruset linijek (stricte) kodu.

[Viters]

@frogi16: No w porządku. Rozumiem, że są różne podejścia do tego. Pewnie zależy to od indywidualnego stylu albo stylu przyjętego w projekcie. Ale nie rozumiem po co starasz się mnie do czegoś przekonać, skoro ja zadałem pytanie dotyczące innej sprawy?

[f.....6]

@Viters: napisałem ci gdzie robisz błąd, a ty usilnie udowadniasz że jednak masz rację. Nie obchodzi mnie co z tą wiedzą zrobisz, ale miej trochę szacunku i nie obrażaj się jak skarcone dziecko.

[Viters]

@frogi16: Ja się nie obrażam i niczego nie udowadniam. Napisałem przecież wyżej, że rozumiem. Przyjmuję do wiadomości co napisałeś i jeśli zajdzie taka potrzeba, to się do tego dostosuję. Albo do czegoś innego. Zadałem po prostu inne pytanie i to zaakcentowałem w poprzedniej wiadomości. W szczególności nie rozumiem, gdzie zachowałem się jak skarcone dziecko. Albo gdzie naruszyłem Twój szacunek.

[f.....6]

@Viters:

ale nie rozumiem

napisałem przecież wyżej, że rozumiem

I prowadź tu człowieku dyskusję...

[Viters]

@frogi16: No tak, prowadź dyskusję z kimś, kto nie do końca potrafi czytać ze zrozumieniem. Wyjaśnię więc: rozumiem Twoje stwierdzenie o tym, że komentowanie wszystkiego nie musi mieć sensu. Nie rozumiem natomiast, dlaczego nazywasz mnie skarconym dzieckiem.

[f.....6]

@Viters:

zachowujesz się jak skarcone dziecko

nazywasz mnie skarconym dzieckiem

Zaklamywanie rzeczywistości część kolejna. Jak powiem że wyglądasz jak Stalin to znaczy, że uważam, że tak się nazywasz?

[Jaslanin]

@Viters: tak naprawdę to nie da się na to odpowiedzieć, bo nie wiadomo jaka jest tego logika biznesowa itd. ale ogólnie dziedziczenie to jest śliski temat bo łatwo wpaść w pułapkę fragile base class (zmiana w klasie bazowej spowoduje nieoczekiwane skutki w klasach poniżej, problem narasta gdy struktura dziedziczenia rozrasta się powyżej 3 poziomy i gdy wiele jest use caseów klasy bazowej). Dlatego między innymi popularna jest konwencja composition over inheritance.

[Viters]

@Jaslanin: Akurat dziś czytałem ten temat na SO :) W tym przypadku jednak chciałem skorzystać ze standardowego sposobu dziedziczenia i mam ku temu konkretne powody.

Tak też myślałem, że nie ma konkretnej odpowiedzi na moje pytanie, dlatego chodzi mi o opinie. Przede wszystkim chciałem dowiedzieć się, czy któryś ze sposobów jest szczególnie zły i potępiany (np. właśnie powielanie dokumentacji w klasie dziedziczącej).

Dzięki za rozbudowaną odpowiedź. Miła odmiana :)

[Jaslanin]

@Viters: odnośnie samych komentarzy to nie wiem jak w CPP, ale w innych językach są specjalne tagi dla dokuemntacji które informują że klasa powinna dziedziczyć dokumentacje, a IDE samo sobie radzi z przekopiowaniem dokuemtacji

[Jaslanin]

@Viters: no i jeszcze ogółnie odnośnie komentarzy to nie ma sensu ich praktycznie dodawać dla getterów, bo dodwanie komentarzy w stylu get property x spowoduje że po pewnym czasie Ty / inni programiście zaczniecie omijać czytanie komentarzy bo zawierają bezużyteczne czy łatwe do znalezienia w kodzie informacje, raczej komentarze należy dawać w jak najmniejszej ilości miejsc, wtedy jest szansa że czytający nie będzie ich ignorował bo będzie wiedział że to coś