Czytelność kodu

[gamer.cpp]

Spora część osób na początku nauki programowania ma problem z pisaniem czytelnego kodu (doświadczenia wyniesione z lekcji informatyki, sprawdzanie kodu z czterema pętlami zagnieżdżonymi bez ani jednego wcięcia to masochizm) dlatego zebrałem kilka podstawowych zasad "czytelnego programowania" i umieściłem w jednym miejscu. Dla większości może wydawać się to banalne ale mam nadzieje, ze ktoś z tego skorzysta.


1. Komentarze

Czyli krótkie opisy fragmentów kodu. Dużo prościej zrozumieć porządnie wykomentowany kod niż ten bez komentarzy.  Łatwiej też połapać się w kodzie pisanym jakiś czas temu Wyróżniamy dwa rodzaje komentarzy:

- Jednoliniowy (umieszczany za dwoma ukośnikami). Stosowany do krótkich i zwięzłych komentarzy.
Przykład:

Kod:

int i; // licznik pętli

- 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).

Przykład:

Kod:

/*
Pierwsza linia
Druga linia
Trzecia linia
*/

2. Wcięcia

Wcięcia to specjalnie stosowane "odstępy" w naszym kodzie. Dzięki nim wyraźnie widzimy gdzie kończy się a gdzie zaczyna nowy blok, np. pętla, instrukcja warunkowa itd. Wcięcie umieszczamy najczęściej w linijce pod klamerką w lewo (w c++, w pascalu wcięcie robimy po instrukcji begin).

Przykład:

Kod:

void Funkcja()
{
(tu robimy wcięcie)
kod po wcięciu (przesuniety w prawo)
kolejna linijka kodu

for(;;)
{
(a tutaj kolejne)
kod w petli
kod w petli 2
}
}

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

3. Nazewnictwo

Kolejna ważna sprawa to to, jak nazywamy nasze zmienne/klasy/funkcje. Nazwy typu asd, dupa itd za wiele nie mówią, więc dobrze jest nazywać zmienne zgodnie z ich przeznaczeniem, np. position_x lub archer.range w przypadku pola klasy.

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:

Typy zmiennych:
i      - liczba całkowita (integer)
f      - liczba zmiennoprzecinkowa (float)
d     - liczba zmiennoprzecinkowa podwójnej precyzji (double)
l      - duża liczba całkowita (long)
c      - znak (char)
b     - wartość logiczna (bool)
dw   - podwójne słowo (dword)
w     - słowo (word)
by lub byte - bajt

Popularne rozszerzenia:
str       - ciąg znaków (string)
h         - uchwyt (handle)
v, vec  - wektor (vector)
pt        - punkt (obiekt zdefiniowany przez użytkownika)
rgb      - paleta kolorów r,g,b (struktura lub typ zdefiniowana przez użytkownika)

Modyfikatory:
p         - wskaźnik na (pointer)
r          - referencja na (reference)
a, ary  - tablica

Zasięg:
m_      - pole klasy
g_       - zmienna globalna
s_       - zmienna statyczna

Dodatkowe prefiksy stosuje sie przy nazewnictwie klas, np:

C    - zwykła klasa, np CFoo
I     - klasa abstrakcyjna wykorzystywana jako szablon
UI   - klasy dotyczące interfejsu (user interface)
S     - singleton

(źródło: pierwszy tom perełek)

Przykładowe nazwy z wykorzystaniem notacji węgierskiej:

Kod:

iSuma               (zmienna typu integer)
fWynikDzielenia (zmienna typu float)
CKlasaBohatera         (klasa)
SLogger      (singleton)
m_iPunktyZycia (pole klasy, typ int)
g_Device      (zmienna o zasięgu globalnym)

Jak widać prefiksy można łączyć (m_iPunktyZycia mowi nam ze zmienna jest polem klasy i jest typu int).

Kolejnym aspektem nazewnictwa jest oddzielanie nazw kilkuwyrazowych. Tu gusta są podzielone, można pisać na różne sposoby, oto kilka z nich:

pierwszyDrugiWyraz,
PierwszyDrugiWyraz,
pierwsz_drugi_wyraz.

Każdy wybiera jak mu najwygodniej, ja preferuje zaczynanie każdego wyrazu wielką literą.

Bonus:

Linki do dyskusji związanych z tematem:
http://forum.gamedev.pl/index.php/topic,1117.0.html Kod - po polsku czy po angielsku?
http://forum.gamedev.pl/index.php/topic,3502.0.html Zaawansowani a komentarze w kodzie

Fajnie by było jakbyście podsunęli swoje pomysły jak pisać czytelny kod, chętnie wyedytuje posta i dodam wasze patenty Aha, jeśli znalazłeś błąd to napisz PM-kę, poprawię.

[Xion]

Z notacją węgierska bym się kłócił. Kiedyś byłem jej fanem, teraz odchodzę od niej coraz bardziej i pewnie za parę lat całkiem z niej zrezygnuję IMHO w nowoczesnych IDE i tak nie ma problemu z szybkim określeniem, czy ta nazwa jest zmienną, jakiego typu, itd., i dodatkowe zaciemnianie tychże nazw dziwnymi przedrostkami niczemu dobremu raczej nie służy.

Co do pomysłów: komentarze ładnie się sprawdzają do "tytułowania" i oddzielania fragmentów kodu:

Kod:

// ten kod robi coś
KodRobiacyCos();

// ten kod robi co innego
KodRobiacyCoInnego();

Kod:

void Klasa1::Funkcja()
{

}

/*************************/

void Klasa2::Funkcja()
{

}

[vashpan]

Hm, co ciekawe tak samo powoli notacja wegierska zaczyna mnie denerwowac... Niedawno uznalem ze to jest bez sensu, no bo przed czym niby ma nas uchronic ? Dobrym pomyslem jest chyba tylko oznaczanie zmiennych globalnych przedrostkiem g. Zreszta przy rozbudowanych typach to nachodzi problem. Jak oznaczac wskazniki do obiektow alokowanych dynamicznie, tablice, czy inaczej niz wskazniki, etc itd...

Za to wciecia... Coz jest sporo szkol, a ja wrecz fanatycznie nienawidze popularnego w Javie i srodowisku OS czegos takiego:

Kod:

void foo() {
  if(x == 1) {
     y = 5;
  } else {
     y = 1;
  }
}

Po prostu cos strasznego jak sie na to patrze... Prawie jak bez wciec w ogole ;p

[yarpen]

Wiele zalezy od jezyka. W C++ notacja wegierska wiele sensu (praktycznego) nie ma. A co do komentarzy, to im mniej - tym lepiej

[gamer.cpp]

A co do komentarzy, to im mniej - tym lepiej

To fakt lepiej postawić na jakość niż ilość ale zero komentarzy to imo masakra Szczególnie jak się czyta cudzy kod.

Hm, co ciekawe tak samo powoli notacja wegierska zaczyna mnie denerwowac... Niedawno uznałem ze to jest bez sensu, no bo przed czym niby ma nas uchronic ?

To rzecz własnych upodobań ale wg. mnie dobrze zapoznać sie z notacją chociażby ze względu na częste jej używanie, np. w tutorialach. Ja na początku nie wiedziałem skąd te nazwy z kosmosu

[Antrykot]

1. Komentarze

Czyli krótkie opisy fragmentów kodu. Dużo prościej zrozumieć porządnie wykomentowany kod niż ten bez komentarzy.  Łatwiej też połapać się w kodzie pisanym jakiś czas temu Wyróżniamy dwa rodzaje komentarzy:

- Jednoliniowy (umieszczany za dwoma ukośnikami). Stosowany do krótkich i zwięzłych komentarzy.
Przykład:

Kod:

int i; // deklaracja zmiennej i

Krótki może tak, zwięzły to już raczej nie Każdy widzi że to jest i. Chyba lepiej napisać do czego ta ma być

[yarpen]

Jeszcze lepiej nie stosowac takich nazw zmiennych i nie pisac nic.

[nilphilus]

http://lazyfoo.net/articles/article02/index.php

tutaj jest taki króciutki artykulik na ten temat ;-]

[Netrix]

Ja osobiście preferuję komentarze i wcięcia typu:

Kod:

// Funkcja main
int main()
{
       // komentarz
       return 1;      // komentarz
}

Stosuje tabulatory, aby ładnie odgrodzić jedno od drugiego. Funkcje odgradzam tak jak Xion, dzięki zwijaniu funkcji z Visuala wszystko jest czytelne.

Póki co myślę nawet, że dobre komentarze w nagłówku wystarczą mi za dokumentacje (chociaż to mogę zmienić).

[Krzysiek K.]

Pozwolę sobie dopisać parę wyjątków:

1. "Złe" komentarze
Czyli jak nie pisać kodu:

Kod:

int main()       // funkcja główna programu
{
    int i;       // zmienna całkowita
    i = 5;       // przypisz pięć do i
    while(i>0)   // wykonuj pętlę dopóki i jest większe od zera
    {
        printf("%d\n",i);    // wypisz i na ekranie
        i = i - 1;           // odejmij jeden od i
    }
    return 0;    // koniec programu
}

Jeżeli potrzeba więcej przykładów, polecam NeHe - tam 50% komentarzy jest tego typu.

2. Wcięcia - tak, ale nie zawsze
Wystarczy porównać dwa kody:

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;
}

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; }

Jak widać, nie zawsze wcięcia poprawiają czytelność.

Osobiście preferuję wersję trzecią, chociaż tu trzeba już wiedzieć, jak działa operator ,:

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;

[shyha]

W NeHe komentarze tak wyglądają bo to nie jest tylko kurs OGL ale również kod dla 'początkujących w ogóle' albo 'profesjonalistów inaczej'

[Krzysiek K.]

W NeHe komentarze tak wyglądają bo to nie jest tylko kurs OGL ale również kod dla 'początkujących w ogóle' albo 'profesjonalistów inaczej'

Tak, tyle że czasem wyglądają tak, jakby były pisane po to, aby skomentować każdą linijkę, a nie cokolwiek wyjaśniać.

Co lepsze perełki wyłowione z pierwszej lekcji NeHe:

Kod:

if (fullscreen) // Are We In Fullscreen Mode?

hRC=NULL; // Set RC To NULL
hDC=NULL; // Set DC To NULL
hWnd=NULL; // Set hWnd To NULL
hInstance=NULL; // Set hInstance To NULL

WindowRect.left=(long)0; // Set Left Value To 0
WindowRect.right=(long)width; // Set Right Value To Requested Width
WindowRect.top=(long)0; // Set Top Value To 0
WindowRect.bottom=(long)height; // Set Bottom Value To Requested Height

static PIXELFORMATDESCRIPTOR pfd= // pfd Tells Windows How We Want Things To Be

active=TRUE; // Program Is Active
active=FALSE; // Program Is No Longer Active

if (msg.message==WM_QUIT) // Have We Received A Quit Message?
done=TRUE; // If So done=TRUE

Ale absolutnie rekordowym komentarzem jest i tak:

Kod:

return FALSE; // Return FALSE

[Zene]

C++ Programming Style Guidelines

[Reg]

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?

[Zene]

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?

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