Zaawansowani a komentarze w kodzie

[Charibo]

Jesli linuxowcy naprawde sie do tego stosuja, to juz wiem dlaczego opensource'owy kod jest taki nieczytelny

[Chester2000]

Komentarze powinny być (oczywiście tam gdzie jest to dla nas konieczne). Ważne jest poprawne nazewnictwo funkcji i zmiennych. A długość kodu w funkcji  - bezsens czasem trzeba przekazać do obiektu kilka zmiennych i co jak się nie zmieszczą to mam ich nie przekazywać tylko przerabiać cały kod  albo nazwać zmienne w funkcji -  a, b, c, d, e ,f itd ? . Czytelność kodu jest ważna ale dobry komentarz przy bardziej rozbudowanych funkcjach (bądź realizujących skomplikowane zadanie ) wypadało by dać - ułatwi to korzystanie np: z metody silnika który jako parametr potrzebuje takich danych w takiej postaci a zwraca obiekt lub dane w takiej postaci. Zmniejsza to ilość błędów podczas tworzenia kodu z wykorzystaniem metod a także oszczędza czas jaki musielibyśmy stracić na sprawdzanie ciała klasy silnika która to zadanie realizuje.   

[k_b]

Owa "zasada" to oczywiście jest żart, który należy traktować w kategoriach żartu, dlatego bez przesady Chester2000. Ja sam w ciałach funkcji stosuję komentarze tylko do rozdzielenia poszczególnych jej sektorów (oraz na początku ogólny opis, czyli co robi, do czego służy, itd.) i nie możliwe byłoby u mnie przestrzeganie tego zdania.

[Chester2000]

k_b - wiem, wiem spokojnie Może trochę za "mocno "to skomentowałem .

[Moriturius]

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.

Albo wziąć większy monitor

[counterClockWise]

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.

Albo wziąć większy monitor

Albo zwiększyć rozdzielczość

Co do komentarzy - to zależy od charakteru projektu i ile osób potencjalnie będzie musiało to czytać. Ale osobiście zastraszającą mało komentuje (chociaż uwielbiam wszelkiego rodzaju dokumentacje - i to najlepiej ładnie wyglądającą, antyaliasing tekstu, dużo obrazków, jeśli jakieś wzorki to TeX...
W zasadzie podobnie jak inni w kodzie komentuje głownie przy deklaracji klas - np. lubie w .NET komentarze /// przed deklaracją metody - że widać przy wywoływaniu krótki opis parametrów, zwracanego wyniku itd.

[Asmodeusz]

Jeśli funkcja wymaga podziału na części logiczne, należy ją podzielić na mniejsze funkcje. Komentarzy w kodzie unikam jak ognia - jeśli coś wymaga skomentowania, oznacza to zły projekt. Dlatego też dokładny opis modułu (z datą powstania, datą aktualizacji, opisem działąnia, wymienionymi używanymi modułami, stosowanymi namespaces itp.), do tego opis klasy (zasady użycia, co zawiera, z czym jest związana, gdzie wykorzystywana), opis każdej z metod (działąnie metody, rzucane wyjątki, opis parametrów wraz z wartościami granicznymi, złożoność obliczeniowa (jeśli jest potrzebna) oraz obszerna dokumentacja główna z założenia wystarczają. Kod zamierzam opublikować na licencji edukacyjnej public domain (kod może być wykorzystywany do nauki i analizy, ale nie można go użyć we własnych produkcjach - nawet niekomercyjnych), więc i okomentowanie powinno być czytelne. A dokumentacja poza komentarzami to tylko UMLowe diagramy, które traktuję jako integralną część projektu.

[Riddlemaster]

Komentarzy w kodzie unikam jak ognia - jeśli coś wymaga skomentowania, oznacza to zły projekt.

Nie zgodzę się z tym. Wystarczy wyobrazić sobie krótką ale skomplikowaną funkcję (np. jakieś hardcore'owe optymalizacje w asmie ). Nie oznacza to, że projekt jest zły, a jednocześnie bez umieszczenia komentarzy ktoś kto będzie ten kod konserwował będzie musiał się przegryźć przez każdą jego linię.

[Liosan]

A ja uważam, że prawda jest tam gdzie komu wygodnie :] Spójrzmy na duże, profesjonalne firmy. Z jednej strony są takie, które trzymają się zasady max 1 ekran/funkcję, piszą więcej komentarzy niż kodu i więcej dokumentacji niż komentarzy. Z drugiej strony, taki np. Comarch (konkretnie jego warszawski oddział research&development) ZABRANIA komentowania kodu - tak jak mówi Asmodeusz, jeśli komentarz jest potrzebny to znaczy, że coś jest nie tak. Zresztą, oni dokumentacji też unikają

Liosan

[Gravell]

Gdzieś czytałem, że przy pisaniu Windows 98 komentarze (ich waga) kilkukrotnie przewyższały wagę (MB) samego programu

[Reg]

Hej, przydałoby się napisać program liczący stosunek komentarzy do kodu :) Przy okazji jeszcze średnią długość nazw zmiennych, funkcji itp.

Nie wiem jak można zabraniać pisać komentarze. Rozumiem, że bez sensu jest pisać:

Kod:

// Ta pętla przebiega po całej tablicy
for (uint i = 0; i < Rozmiar; i++)
  ...

Ale jak checie bez komentarza zaznaczyć, że dany parametr wskaźnikowy w C++ jest wyjściowy a nie wejściowy albo wejściowo-wyjściowy, że ma być z zakresu od 0 do 1 albo że może/nie może być NULL???

[vashpan]

Co do komentarzy w C::B jest fajny plubin ( standardowo ) liczacy statystyki kodu w projekcie - ilosc linijek kodu, komentarzy, bialych znakow i procentowy udzial tego wszystkiego....

Naprawde nie rozumiem jak mozna zabraniac pisania komentarzy... Czlowiek to nie komputer - a co jezeli zapomniesz pewnego triku, w bardzo waznym fragmencie kodu, poza tym nawet jezeli kod bedzie w miare prosty to i tak szybciej jest przeczytac komentarz niz zastanawiac sie - nawet krotko - jak to dziala.... Przy prjektach wielkich gdzie sa setki tysiecy linijek kodu nei wyobrazam sobie zeby nie pisac objasnien, chocby po to zeby nie zapomniec... O dokumentacji juz nei wspominam.......

[RageX]

Właściwie... pytanie należałoby rozciagnąć o hasło "dokumentacja", nawet błacha.
Dokumentacja to mus jeśli nie piszesz czegos sam, albo jeśli jesteś przekonany że kod będzie długo leżał. Do dokumentacji śmiało można zaliczyć komentarze.

Ja mam tak - oczywiście minimalizuje ilość komentarzy dopóki nie stworzę prototypu kodu, ale jak już dany fragment kodu, idzie na "półkę", to dopisuje co nieco komentarzy + Info w głównej dokumentacji.

Ważnym też jest aby nie śmiecić komentarzami, minimalizować rozsądnie linijki kodu.

[bies]

Ale jak checie bez komentarza zaznaczyć, że dany parametr wskaźnikowy w C++ jest wyjściowy a nie wejściowy albo wejściowo-wyjściowy, że ma być z zakresu od 0 do 1 albo że może/nie może być NULL???

Nie nadużywać wskaźników, od tego są stałe i zwykłe referencje. Użyć typu range<float, 0, 1> lub asercji. Użyć referencji gdy nie może być NULL, wskaźnika gdy NULL jest dopuszczany, lub asercji.

[Liosan]

Ale jak checie bez komentarza zaznaczyć, że dany parametr wskaźnikowy w C++ jest wyjściowy a nie wejściowy albo wejściowo-wyjściowy, że ma być z zakresu od 0 do 1 albo że może/nie może być NULL???

Asercje, konwencje nazewnictwa, i zasada "wszyscy wiedzą jak wszystko działa" ?

@góra: no właśnie

Dokumentacja to mus jeśli nie piszesz czegos sam, albo jeśli jesteś przekonany że kod będzie długo leżał. Do dokumentacji śmiało można zaliczyć komentarze.

Przesadzasz... ostatnio modne jest programowanie agilne (ble, obrzydliwa konstrukcja językowa) - ostatnio pojawił się art Riddlemastera w tym temacie. Ta metodologia nie wymusza dokumentacji ani zbytnio nie zachęca Po prostu uznaje się ją za zbędną, czyli w nadmiarze szkodliwą.