Dodaj do ulubionych

Czytelność kodu. Komentarze.

08.02.06, 09:17
Edytor zaawansowany
  • nancyboy 08.02.06, 09:20
    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 08.02.06, 10:28
    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 -- jakies bardziej zawile petle,
    rozgalezienia, niskopoziomowe operacje, a takze w miejscach bardzo waznych z
    punktu widzenia programu.. itd itp

    nie wiem co rozumiesz przez 'zyjacy' projekt. tam gdzie sie wszystko czesto
    zmienia tym bardziej jest szalenie waznezeby komentarze byly zrozumiale a nazwy
    funkcji stabilne! nie ma nic bardziej irytujacego gdy pracujesz z kims nad
    jakims kodem, on ma do napisania m.in funkcje 'getWiekUczestnika' z ktorej Ty
    bedziesz korzystac, i co dziennie w CVS'ie tej funkcji sie zmienia nazwa.. na
    getWiekUczest, podajWiekUczest, getAge.. a Tobie sie co rusz Twoj kod wysypuje
    bo 'nie ma takiej funkcji', no bo on znowu nazwe zmienil.. i wyobraz sobie
    takie cos razy funkcji sto :)

    oczywiscie, jak zaszla jakas wazna zmiana w kodzie. warto zmienic nazwe funkcji
    wlasnie zeby sie wszystkim kod wysypal i przez to zmusic ludzi do zauwazenia
    zmiany. ale opis wszystkich zmian (ktore Ty wprowadziles i sadziles ze sa az
    tak wazne ze az trzeba ludzi zmusic do zauwazenia ich) - powininen byc w
    dokumentacji!! albo w dokumentach projektowych, albo wlasnie w komentarzach,
    one to tez czesc dokumentacji..

    inna sprawa - projekt zazwyczaj ulega modyfikacjom, acz funkcjonalnosc
    poszczegolnych rzeczy zadko. predzej bloki projektu znikaja i pojawiaja sie
    nowe. tak wiec jesli juz jest zrobiony jakis przemyslalny wczesniej projekt i
    nie jest to pisanie "hej chlopaki siadamy i piszemy windowsa":) to projekt dosc
    scisle okresla jak sie maja nazywac funkcje i co robic.. wtedy kazda wymagana
    zmiana musi byc pierwsze wprowadzona do dokumentacji projektu, nalezy zmienic
    opis co funkcja ma robic i ew. nazwe tej funkcji, a dopiero potem mozna
    zabierac se za rzeczywiste updateowanie jej kodu.. inaczej dukumentacja
    projektowa szybko by sie rozjechala z rzeczywistoscia juz po 2-3 modyfikacjach

    i jeszcze inna sprawa -- oj tak.. utrzymywanie (nawet jedynie swoich)
    komentarzy i dokumentacji aktualnych wzgledem kodu to strasznie upierdliwa
    sprawa.. ale sie tego nie przeskoczy niestety. chcialoby sie zastosowac jakies
    skrotowe kodowanie opisu w nazwie, np. ustawMojeDane_Icp_Ncp_nameX() co by
    mialo znaczyc 'imie-char*','nazwisko-char*','ew. wyjatek nameException'.. tylko
    pomysl jak strasznie komus by sie korzystalo z tych funkcji jesli by keidys byl
    zmuszony pisac w srodowiku bez autouzupelniania :) poza tym co to jest Icp Ncp
    nameX tez gdzies trzeba opisac :)
  • nancyboy 08.02.06, 11:03
    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 09.02.06, 16:06
    Dobry programista stosuje odpowiednie nazwy zmiennych i komentarze. Marny
    programista produkuje bzdety na caly ekran... Szkoda tego czytac.
  • ktosktomafajnegomisiaczka 10.02.06, 02:53
    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 -- oj, to jak najbardziej sie
    zgodze. Czytajac takie nazwy funkcji, dlugich niczym pelne zdania, to osoba
    czytajaca moze nerwicy dostac.. zobaczy ktos caly kod zapelniony nazwami w
    stylu zoptymalizowan_funcka_mnozaca_dwie_macierze_piec_na_pietnascie() i mamy
    kandydata do kaftana bezpieczenstwa :) nazwy powinny byc opisowe, definiujace,
    ale mozliwie krotkie i konkrente. To czego ewentualnie zabraknie powinno
    znalezc sie w kometnarzu. Calkowicie wystarczy nazwa mnoz_mat_5x15_opt() z
    krotkich komentarzem /*zoptymalizowana funcka mnozaca dwie macierze piec na
    pietnascie*/ :)

    [Swoja droga, to tez pytanie *co* jest napisane w komentarzach :) Sztuka
    opisywania kodu jest conajmniej tak trudna jak jego pisania:) Komentarze
    powinny zawierac pelnie tresci ktore sa wymagane do wyajsnienia, ale tak
    krotkie jak tylko sie da! Inaczej czytelnik sie zanudzi na smierc, albo zacznie
    skakac po tekscie szukajac ciekweych rzeczy i moze cos nie daj boze waznego
    pominac!]

Popularne wątki

Nie pamiętasz hasła

lub ?

 

Nie masz jeszcze konta? Zarejestruj się

Nakarm Pajacyka