Czytelność kodu

[Riddlemaster]

Właśnie o to chodzi, żeby nie było "tricky code".

To ciekawe, że kod wszystkich profesjonalistów, jaki dotychczas widziałem potrafi być "very tricky" momentami... i niemal zawsze pozbawiony komentarzy

[yarpen]

Ja nie używam notacji węgierskiej w C++, za to używam w PHP, Python i innych językach bez kontroli typów.

co do komentarzy, to im mniej - tym lepiej

Możesz rozwinąć co przez to rozumiesz? Bo to brzmi intrygująco. Jakie sztuczki w kodzie polecasz, żeby potrzebne było jak najmniej komentarzy?

Nie tyle sztuczki, co zdrowy rozsadek. Komentarze jak w przykladzie podanym przez Krzyska (z Nehe) nie maja zadnego sensu. Komentarze objasniajacy co trzyma zmienna albo co robi f-kcja sa w 90% zbedne i mozliwe do zastapienia przez jasne nazewnictwo. Podstawowa "sztuczka" tak naprawde jest taka: kiedy masz ochote skomentowac jakis kawalek kodu, pomysl czy nie da sie go zapisac tak, by komentarz byl zbedny. Najprostszy przyklad to chocby komentowanie "blokow" w f-kcjach - w wiekszosci przypadkow mozna tego uniknac opakowujac blok w odrebna f-kcje (niech nawet bedzie lokalna) i nazywajac ja odpowiednio. Czesc komentarzy mozna zastapic pakietem unit testow, ktore maja ta zalete, ze zawsze sa aktualne. Akceptowalne komentarze to glownie te opisujace pre/post conditions f-kcji.

[sobol]

Dlatego ja unikam osobiście komentowania pojedynczych linii kodu, staram się komentować większe kawałki - co dany kod robi, jak robi etc. IMO źle użyte komentarze zaciemniają kod, czyli są gorsze niż ich brak

[Esidar]

W tej chwili mamy 2 wątki o komentarzach w kodzie ale napiszę tutaj.

Ja używam komentarzy w 99% do formatowania tekstu, żeby był czytelniejszy (oddzielanie bloków kodu, funkcji wykonujących dany rodzaj operacji, itd). I jeśli piszę komentarzy do mam na myśli

Kod:

//-------------------------------

Bardzo sporadycznie zdarza mi się dopisać komentarz w postaci objaśnienia, do deklaracji zmiennej gdy powinna mieć krótką nazwę np. Name a w tej samej klasie będzie kilka tego rodzaju zmiennych. Więc wtedy daje adnotację, że ten Name to służy do tego a ten FileName do tego.

Nigdy nie stosuje komentarzy jako zastępstwo dokumentacji. Z takimi komentarzami (tak jak z dokumentacją) zawsze jest ten problem, że może łatwo stracić na ważności i stać się bardziej myląca niż pomagająca. Uważam, że lepiej jest blok kodu odpowiednio sformatować i wyznaczyć jakiś ważny element dodatkowym enterem albo dodatkową linią

Kod:

//-------------------------------

i to już wystarczy żeby pomóc zaanalizować kod.

Komentarze słowne jako dokumentacja są zbyt często mylne. Jeśli są za krótkie to nic nie wyjaśnią, a jeśli są za długie to skutecznie zaciemnią sam kod. Nienawidzę wręcz tego co często jest w open source'ach czyli 30kB tekstu w pliku .h (zamiast dokumentacji w .html) a pomiędzy gdzieś tam ukryte są 3-4 funkcje.

Wystrzegam się też komentarzy "wielolinijkowych" /**/. Nowe IDE (jak chociażby VS) pozwalają na comment/uncomment całych bloków kodu za pomocą jednej kombinacji klawiszy. Wielolinijkowce dodatkowo mają tą wadę, że nie da się zakomentować większego bloku, jeśli gdzieś w środku jest już użyty inny komentarz wiel.

[Kurak]

Kod:

int i; // licznik pętli

Przesada

- Wieloliniowy (umieszczany pomiędzy /* a */). Stosowany do dłuższych opisów fragmentów kodu, można także używać go do umieszczania belki z informacjami "na górze" pliku (na przykład autor, kontakt itd).

Ta "belka z informacjami" to jedyne miejsce gdzie takich komentarzy używam. Jak już chcę się tymczasowo pozbyć jakichś kawałków kodu - Ctrl+K+C

Wcięcie tworzymy stawiając kilka spacji lub tabulacje.

Wcięcia robione ze spacji są niewygodne - ja zdecydowanie preferuję tabulatory. Czasem zdarza mi się czytać kod bez wcięć albo z dwuspacjowymi wcięciami - straszne.

Bardzo przydatną sprawą jest tak zwana notacja węgierska, czyli systematyka nazywania zmiennych. Polega ona na dodawaniu przedrostków określających czym jest zmienna (jej typ, zasięg itd). Najczęsciej używane przedrostki notacji węgierskiej:

Ja notację węgierską w C++ uważam za kombinowanie Cośtam używam, ale szczątkowo - pola klasy poprzedzam pojedynczym "m" (fajna współpraca z Visualowym IS - m, Ctrl-spacja i mamy ładnie wszystkie pola wylistowane ), a globalne obiekty poprzedzam pojedynczym g. I tyle
Kiedyś używałem też przedrostka "C" przed klasami, teraz już nie. Brzydko wygląda

[Mattrick]

@Kurak
Moja krew, hehe.

A oprócz tego co Kurak wymienił ostatnio zacząłem 'bawić' się kodem jak w wordzie, przez co jest on IMO ładniejszy. Przykładzik kodu: http://nopaste.gamedev.pl/?id=1763.

[Pockey]

Mattrick - ladniejszy?!
ja odbieram go jako kompletnie nieczytelny: niepotrzebne puste linie i pelno spacji poza tym te 30 linii mozna napisac w 10 i bylo by duzo ladniej

ed. np tak: http://nopaste.gamedev.pl/?id=1765 

[unodgs]

Kod:

if(a==1) { b = 2; c = 3; d = 4; }
if(a==2) { b = 3; c = 4; d = 1; }
if(a==3) { b = 4; c = 1; d = 2; }

Tez tak bym to zapisal

Kod:

if(a==1) b = 2, c = 3, d = 4;
if(a==2) b = 3, c = 4, d = 1;
if(a==3) b = 4, c = 1, d = 2;

Tego bym zdecydowanie unikal - nawet mimo znajomosci operatora ,
Ja osobiscie komentuje tylko miejsca gdzie jest zastosowany jakis trik, lub gdzie algorytm wymaga malego opisu, bo zeby wywnioskowac z kodu jak on dziala potrzeba duzo czasu. Sposob dzialania aplikacji, idee umieszczam w osobnym pliku.
Zadnych durnych komentarzy w stylu tu sa konstruktory tu sekcje prywatne etc. Notacje wegierska nalezy jak najszybciej wyrzucic do kosza. Ona jest bez sensu w swiecie obiektowym gdzie klasa opisuje nasz wlasny typ i to ta nazwa powinna jednoznacznie mowic o co chodzi - z tego tez powodu C przed nazwa klasy to najwiekszy shit jaki widzialem, niestety zapoczatkowal to sam MS w MFC. Co do typow prymitywnych tez nie wiem po co komu dw f czy d przed nazwa. To mialo sens w C gdzie wszystkie zmienne musialy byc zadeklarowane na poczatku funkcji. Normalnie zmienna deklaruje sie w miejscu jej uzycia wiec widac jaki to typ. Poza tym jak ktos juz wspominal kazde dobre ide pokaze nam informacje o zmiennej. Juz nie wspominam o tym, gdy zechcemy zmienic np char * na string - co wtedy ? wszedzie bedziemy zmienic psz na str.

[Netrix]

@Kurak
Moja krew, hehe.

A oprócz tego co Kurak wymienił ostatnio zacząłem 'bawić' się kodem jak w wordzie, przez co jest on IMO ładniejszy. Przykładzik kodu: http://nopaste.gamedev.pl/?id=1763.

IMO on ładniejszy nie jest, zwłaszcza niepotrzebne spacje na początku po klamrze. Ja lubię na przykład oddzielać poszczególne fragmenty funkcji linią pustą, ale czasami wychodzi mi tak, że po każdym średniku jest linia przerwy.

[yarpen]

W takich dyskusjach warto rozdzielic sprawy istotne czyli glownie komentarze i nazewnictwo od nieistotnych czyli ile spacji, gdzie klamry itp pierdoly. Pierwsze bede zawsze w moim zespole egzekwowal, drugie olewam. Niech kazdy pisze, jak mu wygodnie, to indywidualna sprawa. A czy to wyglada "ladnie" na ekranie srednio mnie interesuje, poki dziala i widze, co kod robi.

[Firkraag]

Ja bym to zrobił tak: http://rafb.net/p/i6NdxR53.html
Ktoś może się zaśmiać, że ten int bez sensu w osobnej linii,.ale różne są wartości zwracane i z różnych przestrzeni nazw.
Co do notacji węgierskiej to jak paru kolegów wyżej, tylko co najwyżej m_ przed składową klasy i g_ przed zmienną globalną (tego drugiego to prawie u mnie nie ma). Kiedyś pisałem zmienna_ jako oznaczenie składowej klasy ale jest to bardzo brzydkie w takich połączeniach jak np. zmienna_.push_back(a);

[RageX]

Zmienne globalne, lepiej zamknąć w statyczną klasę G, niż wszystkie nazywać g_costam.
Co do spacji, tabulacji... to jest jeden z tych tematów co powodują ogień. Nie będę się w to zbytnio wdawał, powiem tylko że do wcięć albo używamy tabulacji, albo spacji. Mieszanie obu powoduje cyrki. W pythonie tabulacje są interpretowane jako spacje. To rozwiązało problem mieszania tabulacji ze spacjami aczkolwiek zwiększa zużycie pamięci. Sam, do wcięć, używam  samych tabulacji.
Lubię same literki dla zmiennych gdy jest to wystarczające:

Kod:

uint i, j, k;
// lub
uint i0, i1, i2;
// to oczywiste nazwy (jeżeli pisane koło siebie) dla iteratorów

float x, y, z;
// a to oczywiste nazwy (jeżeli pisane koło siebie) dla pól 3-wymiarowego wektora.

My tu na forum, często dla zademonstrowania tylko przykładu używamy liter jako nazw - nie sądzę aby ktoś w swoim kodzie oznaczał klasy A lub B.

Od tego

Kod:

if(a==1) { b = 2; c = 3; d = 4; }

wolę to

Kod:

if a == 1
        b = 2
        c = 3
        d = 4

Takie wyrażenie można zwinąć (w niektórych środowiskach) plusem. I o ile nie interesuje mnie ten przypadek, nie muszę wiedzieć co się stanie. No i jest logicznie kompatybilne z "instrukcja per linia".

Nie lubię belki informacyjnej... otwarcie pliku na nowo wiąże się z oglądaniem tego. Zniosę to jeżeli można je zwinąć podobnie jak blok includeów czy usingów. Wolę dokumentację oddzielnie(po co ma sie narzucać gdy jest niepotrzebna), podobnie drażnią mnie xmlowe komentarze wewnątrz źródeł, w Javie i C#'ie. Wolałbym żeby te komentarze wraz z symbolami funkcji, klas były w osobnym pliku/plikach dołączonych do projektu który można modyfikować z poziomu projektu, np. w jakiejś osobnej zakładce.

[hacer]

Kod:

int i; // licznik pętli

Przesada

IMHO tutaj nie ma może przesady tylko złe podejście. Zamiast pisać jakiegoś komentarza można zamiast int i napisać int iLicznik Jeśli mamy np. mała pętle

Kod:

for(int i=0; i<10;i++){}

no to to raczej nie ma sensu ale są momenty gdzie po kilkudziesięciu liniach kodu w koncu pojawi sie ta zmienna i można szybko wywnioskować do czego to służy. Również na podstawie nazwy zmiennej można wywnioskować czy coś liczymy czy odnosimy sie do jakiejś tablicy.

[k_b]

Cytuję (z pamięci) z "Pragmatycznego programisty":

źle napisany kod wymaga obszernych komentarzy

Kod:

int i; // licznik pętli

Przesada

Nie przesada, jeśli doda się jeszcze parę słów na temat pętli, do której ów licznik należy, na przykład:

Kod:

int i; // licznik pętli wczytującej powierzchnie kafli

W moim stylu komentarze i ogólnie pojęta czytelność ciągle się zmieniają. Co prawda, w jednym pliku już pod żadnym pozorem nie zmieszczę 60 kilobajtów ( ), unikam także wielkości większej niż 20 KB - idzie na lepsze.

Zamiast wszelorakich przedrostków zmiennych, zdecydowanie bardziej preferuję wsadzenie takich zmiennych w namespace. Przykładowo:

Kod:

namespace GUI
{
    T_Button Button[20];
    T_Background Background[10];

    bool Load_Backgrounds( );
}

namespace Gameplay
{
    T_Enemy Enemy[40];
    T_Map Map;
   
    bool Load_Map( std::string file_path );
}

Jak widać też na powyższym kodzie, nie lubię pisać KurnaChata, tylko Kurna_Chata - a własne typy danych poprzedzam T_ . Oprócz tego, nie piszę praktycznie żadnych funkcji void, zwracanie u mnie powinno następować zawsze.

[raver]

Klasy:

Kod

class MESH
{
    public:
        int num_vertex;
        vec3d* verticles;
};
 

Enumeracje:

Kod

enum EGAMESTATE
{ 
    EGS_START,
    EGS_PLAY,
    EGS_SPLASH
};
 

Funkcje:

Kod

int min(int a, int b)
{
    return a<b ? a : b;
}
 

Plus do tego ładny opis co jest w pliku na górze i dobrze sobie radzę

Nie stosuję żadnych namespace'ów, czy innych rzeczy, imo są one niepotrzebne, tylko zaśmiecają kod i utrudniają pisanie.

PS:

(fajna współpraca z Visualowym IS - m, Ctrl-spacja i mamy ładnie wszystkie pola wylistowane )

i powiedział to koleś, który się o to samo czepia...
EDIT: nie chce się kłócić , bo to pierdoła