Zaawansowani a komentarze w kodzie

[bies]

- doświadczeni programiści najczęściej nie robią zbyt wiele komentarzy

Tak przy okazji, zawsze mnie zastanawiało czemu bardziej doświadczeni programiści jak ognia unikają stosowania komentarzy, mimo że większość z nich zgodzi się pewnie, że jest to dobra praktyka.

Bo zbyt wiele rzeczy uważają za oczywiste. Dlatego później muszą nowym osobom w zespole dużo tłumaczyć.

[oy]

Z tego co piszecie wynika, że są tylko newbie, których nikt nie chce i "doświadczeni programiści", a pomiedzy jest wielka próżnia

[Krzysiek K.]

- doświadczeni programiści najczęściej nie robią zbyt wiele komentarzy

Tak przy okazji, zawsze mnie zastanawiało czemu bardziej doświadczeni programiści jak ognia unikają stosowania komentarzy, mimo że większość z nich zgodzi się pewnie, że jest to dobra praktyka.

Ja na przykład ich nie unikam jak ognia, tylko po prostu nie piszę rzeczy, które uważam za oczywiste, bo takie komentarze tylko zaciemniają obraz kodu. A że przy dobrym nazewnictwie zmiennych i sporej praktyce w kodowaniu 99% rzeczy jest oczywistych, to inna sprawa.

[Riddlemaster]

Bo zbyt wiele rzeczy uważają za oczywiste. Dlatego później muszą nowym osobom w zespole dużo tłumaczyć.

No ale wiele algorytmów czy technik, które stosuje się w kodzie jest nietrywialnych (nie mówię o opisywaniu każdej zmiennej, ale o naprawdę problematycznych fragmentach kodu). W ten sposób pozostali członkowie zespołu (nawet nie ci nowi) mają (albo mogą mieć) problem z jego zrozumieniem. Więc coś, co teoretycznie miało nie wymagać opisywania, jednak go wymaga - tylko w formie opisu słownego. Bez sensu Ja tam zawsze komentuję kod - dotychczas nikt nie narzekał.

Z tego co piszecie wynika, że są tylko newbie, których nikt nie chce i "doświadczeni programiści", a pomiedzy jest wielka próżnia

Coś w tym jest Ale zamiast narzekać na swój los, niech newbie wezmą sprawy w swoje ręce. Niech zaczną pisać prostą gierkę, niech zdobywają doświadczenie, a po kilku latach sami nie będą chcieli w swoich teamach kompletnych beginnerów.

[mINA87]

Mnie się po prostu nie chce pisać komenatrzy. Tzn takich inline, bo zawsze staram się obszernie okomentować klasy i metody w formacie doxygen'a i w design doc'ach. Odnośnie samego kodu to standardowe podejście - ciała metod jak najprostsze - wtedy unikamy problemów z niezrozumieniem, bardziej skomplikowane fragmenty tak czy tak są przeważnie zbyt abstrakcyjne, więc warto je trzymać hermetycznie i ich komentowanie nie ma zbyt dużego sensu - lepiej gdzieś na boku opisać cały algorytm. A dobrymi komentarzami mogą być odpowiednie wcięcia, nazwy zmiennych - formatowanie kodu. Schludnie napisany kod to połowa sukcesu. Poza tym komentarze nie mówią nic o kontekście a ten jest przeważnie najistotniejszy dlatego często szybciej daję sobie radę z analizą i poprawkami kodu który jest dla mnie totalnie abstrakcyjny analizując go w debuggerze i starając się go zreversować :]
//edit: Dla porównania rozmowy z twórcą kodu czy czytanie komentarzy nie za dużo mi dają

[Reg]

Ja rzadko piszę komentarze w ciele funkcji - co najwyżej żeby sobie podzielić go na sekcje. Sporadycznie czuję się w obowiązku opisać dlaczego zrobiłem taki a taki hack i jak to działa Natomiast piszę dużo komentarzy przy deklaracjach, gdzie staram się jak najjaśniej wyspecyfikować co funkcja robi, czego wymaga, kiedy wolno ją wywoływać, w jakich jednostkach i z jakich zakresów są przyjmowane parametry, które mogą być NULL, w ogóle co znaczą itp.

[Demon]

Ja bardzo rzadko komentuję swój kod, najczęściej komentuję zapożyczony kod, którego zrozumienie zajęło mi sporo czasu, wtedy komentuję żeby wiedzieć i nie zapomnieć, aktualnie piszę takiego softwarowego renderer'a i np przy rasteryzacji trójkąta daję komentarze typu:

Kod:

//  p1    p2
//   *----*
//    \  /
//     *
//     p3

Mały offtopic - dlaczego znacznik codei nie działa?

// EDIT by Q8 - bo teraz wystarczy tylko code=

[Charibo]

Ja pisze komentarze, nawet w cialach metod - jednak tylko dla siebie. Moj silnik ma miec w zalozeniu zamkniete zrodla, wiec nikt poza mna nie musi rozumiec mojego kodu. (Oczywiscie mam obszerna dokumentacje)

[Moriturius]

Ja na przykład ich nie unikam jak ognia, tylko po prostu nie piszę rzeczy, które uważam za oczywiste, bo takie komentarze tylko zaciemniają obraz kodu.

Jestem tego samego zdania
Im mniej komentarzy tym lepiej - ale jednocześnie: im więcej wyjaśniają tym lepiej

A że przy dobrym nazewnictwie zmiennych i sporej praktyce w kodowaniu 99% rzeczy jest oczywistych, to inna sprawa.

Najgorzej jest jak ktoś musi później to czytać
Dla twórców kodu niektóre rzeczy mogą być oczywiste a dla czytającego nie, czyli jak to mówią: `punkt widzenia zależy od punktu siedzenia`

[Koshmaar]

Nie potrzebuję komentarzy, kod jest wystarczająco oczywisty.

...

A na serio :-) to robię tak samo jak Reg i mINA87. Ostatnio zauważyłem, że moje podejście ewoluowało wraz z czasem, na początku rzeczywiście pisałem relatywnie dużo komentarzy w kodzie. Teraz skupiam się na pisaniu wysokopoziomowej dokumentacji kodu, opisaniu jak czegoś należy używać, czego nie robić, jak to działa w środku itp. niż klepaniu "przydatnych" komentarzy typu:

Kod:

dupa += 5; // increases dupa by 5

// iterates over array
for (int i = 0; i < 10; ++i)
 { ... }

Wyżej nad komentarze w kodzie cenię sobie przejrzystość, dobre formatowanie, logiczne nazwy zmiennych, dużo whitespaces itp. Staram się aby mój kod nie wyglądał jak: http://mindprod.com/jgloss/unmain.html

Słyszałem jeszcze jeden tekst: "Don't comment your code, code your documentation" :-)

[Riddlemaster]

To chyba ja jestem tu wyjątkiem

Poza dość dokładnymi komentarzami w kodzie i dokumentacją klas w stylu Doxygena, stosowaniem notacji węgierskiej w dość hardcore'owej postaci (kiedyś stosowałem prostszą ) - co akurat niektórym może przeszkadzać, tworzę całe tony pobocznej dokumentacji

[Reg]

Ja też tworzę tony dokumentacji. Piszę ją w plikach TXT. Jest trojakiego rodzaju:

- Tymczasowe projekty robocze, w których spisuję (najczęściej w postaci wypunktowanych list) to co mam zrobić, co się ma po kolei dziać w algorytmie, jakie są opcje itd., kiedy projektuje jakiś trudniejszy fragment kodu. Tych tymczasowych dokumentów nigdy potem nie kasuję.
- Listy TODO, czyli co jest do zrobienia.
- Konkretna dokumentacja która opisuje dokładnie jak się używa danego modułu. Nie zawsze piszę ją do wszystkiego, ale staram się wyjaśnić te co bardziej zamotane mechanizmy (jeśli dany moduł czy klasa wymaga objaśnienia na wyższym poziomie niż to wynika bezpośrednio z komentarzy dokumentujących jej poszczególne metody). Taką dokumentację piszę zwykle już po skończeniu implementacji danego modułu.

[nameczanin]

Ja stosuje technike taka jak Reg. Eleminuje powoli troche przyzwyczajen z pisania komentarzy.Faktycznie staram sie je pisac tak, aby nie "zaciemniac kodu". Absolutnie popieram idee komentowania tylko ciemnych stron kodu, aby je rozjasnic na przyszlosc, zamiast zaciemniania jasnego kodu. Poza tym byla taka anegdota linuksowska [wiele razy wspominana], ze jak kod funkcji nie miesci sie na ekranie, to znaczy, ze nalezy napisac go od nowa. Komentarze pomagaja w pisaniu ciagle od nowa tego kodu

[Krzysiek K.]

jak kod funkcji nie miesci sie na ekranie, to znaczy, ze nalezy napisac go od nowa.

Jak sie wywali komentarze, to może się zmieści. W razie czego można także zrezygnować z wcięć i niektórych znaków nowej linii.

[hans_]

Ja stosuje technike taka jak Reg. Eleminuje powoli troche przyzwyczajen z pisania komentarzy.Faktycznie staram sie je pisac tak, aby nie "zaciemniac kodu". Absolutnie popieram idee komentowania tylko ciemnych stron kodu, aby je rozjasnic na przyszlosc, zamiast zaciemniania jasnego kodu. Poza tym byla taka anegdota linuksowska [wiele razy wspominana], ze jak kod funkcji nie miesci sie na ekranie, to znaczy, ze nalezy napisac go od nowa. Komentarze pomagaja w pisaniu ciagle od nowa tego kodu

ta anegdota to nie nakaz, ale wskazowka aby kod byl bardziej zrozumialy i logiczny i byc moze prostrzy.
nie zawsze da sie przeciez napisac funkcje ktora zmiesci sie na ekranie. chocby ladowanie adresow ponad 300 funkcji ogl za pomoca loadlibrary.