Czytelność kodu. Komentarze.

[nancyboy]

Czytelność kodu. Komentarze.

[nancyboy]

Wiadomo, że często przychodzi nam czytać i zrozumieć kod. Jak uważacie, czy
czytelność i zrozumienie kodu bardziej ułatwiają komentarze czy nazewnictwo
zmiennych i funkcji?
Ja osobiście uważam, że w "żyjącym" projekcie, gdzie wszystko często się
zmienia, komentarze są zwykle już nieaktualne, a więc lepiej używać bardziej
opisowych nazw zmiennych i funkcji.

[ktosktomafajnegomisiaczka]

wazne jest i to i to. nazwy funcji powinny byc w miare krotkie, definiujace co
funkcja robi dla osoby ktora wie o co chodzi. komentarze zaspowinny tlumaczyc
co funkcja robi osobom ktore nie wiedza o co chodzi.. :) no i powinny tam tez
byc informacje o wszystkich specjalnych wartosciach parametrow lub zwracanych,
tzn. ze np. -1 jako wiek oznacza 'nieznany' itp. komentarze powinny tez byc
wszedzie tam, gdzie nastepujacy po nich blok kodu moze byc niezrozumialy przez
pierwsze pare minut gapienia sie na niego

[nancyboy]

Dzięki za taką długą odpowiedź, doceniam włożony w nią trud.
Polemizowałbym jednak w paru miejscach.
Na przykład pisanie dokumentacji projektowej ma sens, gdy projekt jest robiony
na zasadzie: paru speców projektuje system, wymyślają nazwy klas czy funkcji, a
potem wysyłają to koderom do Indii.
Często jednak etapy projektowania i kodowania nachodzą na siebie. I tak jak
mówisz, każda zmiana kodu pociąga za sobą zmianę dokumentacji projektu.
Ja jestem z tych, co to nie lubią czytać instrukcji. Wolę, jak coś działa
intuicyjnie. Czy to telewizor, pralka czy biblioteka kodu.

[cloclo80]

Dobry programista stosuje odpowiednie nazwy zmiennych i komentarze. Marny
programista produkuje bzdety na caly ekran... Szkoda tego czytac.

[ktosktomafajnegomisiaczka]

nancyboy - Jak najbardziej sie zgadzam z tym co piszesz. Rzecywiscie, im
wiekszy projekt tym rola dokumentacji projektowej rosnie. Nie jest jednak tak
ze w malym projekciku wogole moze jej nie byc. Generalnie, gdy piszemy sobie
sami jakis program albo programik, to sobie piszemy, zlewamy komentarze i
dokumentacje i jest wszystko git. To jest nasz programik dla nas. Wiemy o nim
wszystko i jest super. Ale.. zdazylo sie Ci kiedys, powiedzmy w pol roku albo
rok po napisaniu czegos, musiec to potem okomentowac albo poobjasniac co
bardziej zawile fragmenty komus innemu? Albo tez zajrzec ot tak z czystej
ciekawosci do jakeigos kodu lub struktury progrmau ktory napisales 2-3-4 lata
temu i juz za nic w swiecie nie pamietasz tych wszystkich drobych szczegolow i
zalozen poczynionych wtedy podczas pisania? :)

Zareczam, w takich momentach czlowiek pluje sobie w brode ze nie chcialo mu sie
napisac tu czy tam tych dwoch, trzech, czy pietnastu linijek komentarza, czy
chocby drobnego grafiku powiazan funkcji/klas/modulow czy jakiejs innej
jakiejkolwiek formy dokumentacji, ktora by Cie uratowala od wstecznej analizy
kodu..

Drobne nieporozumienie tez chyba tkwilo w tym, ze dla mnie "dokumentacja" to
nie tylko sterta papierzysk projektowych wymaganych przez zleceniodawce,
(papiery to wlasciwie sa glownie wymagane od projektanta a nie programisty :)..
Dokumentacja ktora programista tworzy to sa komentarze i ewentualne readme'ki
jak kometnarz za duzy wyjdzie i kod bedzie zaslaniac:) Nazwy klas, zmiennych i
funkcji to tez czesc dokumentacji. Kompilatorowi przeciez nie preszkadzaloby
nazywanie funkcji F1,F2,F3,F4,..,F94940 itd :)


cloclo80 - wierz mi, "caly ekran" to wcale nie tak duzo jesli chodzi o dlugosc
komentarza i nie dlugosc komentarza pokazuje czy programista byl "dobry"
czy "marny":)
jesli zas chodzilo Ci o nazwy funkcji i zmiennych