Coding Style

Okej.. na forumu sem opazil nesteto folka, ki ne znajo pisat komentarjev, izbirat imen funkcij in spremenljivk... zato pisem ena osnovna pravila kodiranja.
Jaz vedno uporabljam anglesko imenovanje funkcij in spremenljivk.. izkljucno zato, ker so vse built-in zadeve ze v anglescini.. in mesanje angleskega in slovenskega jezika je slabo. Ce so ze vse built-in funkcije v anglescini (open, close, exit..), naj bojo se nase.

1. Enoten stil kodiranja cez cel projekt

- Enotna velikost in stil (insert tabs||spaces) tabulatorjev
- Enoten stil function headerjev
- Maximalna sirina (ponavadi je to 80 ali 100 znakov.. torej razdelite dolge vrstice v vec vrstic, ce prekoracite to mejo)

Torej vsi udelezenci projekta morajo imeti enake nastavitve svojih editorjev, da vse zgleda enako za vse. Vecino editorjev se da nastavit tako da tabulatorji delajo kot so zastavljeni. (osebno uporabljam Visual Studio na windowsih in FTE editor na linuxu.. pri obeh se da nastavit tabulatorje) pri VS.NET -> Tools->Options...->Text Editor->All Languages->tabs

2. Smiselno imenovanje spremenljivk in uporaba madzarske notacije


Madzarska notacija (aka Hungarian Notation) je stil poimenovanja spremenljivk. Pred vsako integer spremenljivko damo naprimer crko 'i'.. naprimer:
int iSelectionCount;

Hungarian Notation... nekaj jih se manjka..
'ul' - unsigned long (UINT32)
'll' - long long (INT64)
'ull' - unsigned long long (UINT64)
'e' - enumeracija
itd...

Spremenljivke pa naj bodo imenovane glede na to cemur so namenjene. Naprimer omenjena spremenljivka 'iSelectionCount' je namenjena hranjenju stevila oznacenih elementov. Uporaba velikih in malih crk je tudi pomembna za razlocevanje med imenom spremenljivke in prefixom madzarske notacije.
Informacije o spremenljiki naj bodo sortirane po pomembnosti od leve proti desne, razlocene z velikimi/malimi crkami... naprimer:
iSelectionCountMin
iSelectionCountMax
szSelectionName

Nekako tako kot ce bi delali s structi..
pSelection->count.iMin
pSelection->count.iMax
pSelection->szName

3. Imenovanje funkcij
Podobno kot spremenljivke, naj bodo jasno poimenovane, da tocno vemo za kaj se gre.

int preveri(char *ime); - To je slabo!

int CheckFileIntegrity(char *szFileName); - to je veliko bolj jasno, in tocno vemo za kaj se gre

se bolje:
int File_CheckIntegrity(char *szFileName); - tako naredimo, ce imamo veliko funkcij za manipulacijo filov..

4. Error Handling
Ok.. veliko vas pise funkcije kar brez returnov ali pa z bool returni, kar je zelo slabo iz stalisca error handlinga.
Ce funkcija ni casovno-kriticna (torej da sam klic funkcije casovno zanemarljiv glede na cas izvedbe) naredite error-handling kot se spodobi.

Naprimer takole:

int CheckFileIntegrity(char *szFilename)
{
    int     iRet = 0;
    FILE   *fdFile;

    fdFile =  open(szFileName, "r");
    if (fdFile == NULL)
    {
        iRet = GetLastError();
        return iRet;
    }    

...

    return iRet;
}

Ce pa je funkcija casovno kriticna.. naprimer izracunavanje normal v kaki 3D aplikaciji, se error-handlinga ne dela.. ampak se zagotovi da je input parameter pravilen.

Torej.. vedno uporabljajte return variable za error-handling, ce je le mogoce.. za output spremenljivke pa uporabljajte 'parameter as output variable' To se pa naredi tako:

int GetStringSize(char *szInput, int *piSize)
{
    if (szInput == NULL) return ERROR_EMPTYSTRING;
    
    *piSize = (int)strlen(szInput);
    
    return NO_ERROR;
}

In potem klicemo funkcijo z:
iRet = GetStringSize(szName, &iSize);
in se nam velikost zapise v iSize.

5. Komentarji
Komentarji so zelo pomembna zadeva pri kakrsnemkoli programiranju. Ce upostevate prejsnja navodila za imenovanje spremenljivk in funkcij, so komentarji znotraj kode potrebni samo redkokdaj. Ponavadi samo ce pride do veliko branchinga, ali pa ce uporabimo kak poseben trik, ki ni viden na prvi pogled.

Zelo pomembni so pa tako imenovani function headerji. Gre za blok komentarja, ki opise kako funkcija deluje. Vsebovati mora:
- Ime funkcije
- naslov funkcije
- Return spremenljivka (kaj vraca in kdaj!)
- INPUT in OUTPUT parametri
- Kratek opis funkcije (kdaj se kaj zapise v OUTPUT)
- Special case scenario (ce je kaka zadeva zaradi cesar funkcija ponavadi faila.. ali kaj podobnega)
- Mozni flagi! (ce imamo kak flag parameter, napisite se vse mozne flage in kaj naredijo)

Recimo function header za prejsnjo funkcijo GetStringSize:

/*******************************
* GetStringSize
*
* Gets size of specified string
*
* /INPUT/ char *szInput    Input string
* /OUTPUT/ int *piSize     Output string length
*
* return:
* On success returns NO_ERROR
*
* description:
* Gets size of string szInput and puts it's size into piSize.
*
* If szInput is NULL, function fails and returns ERROR_EMPTYSTRING
*
 *******************************/

Bom verjetno se kej napisal.. sam tolk za zdele.

Naj da moderator to za sticky

jaz programiram tako, da so zaviti oklepaji v novi vrstici, kar pa notaciji ne ustreza.

kriminalc!

Samo se nekaj ... gotoji za errorhandling v Cju rulz ;) Marsikdo pravi, naj se gotoji nikoli ne uporabljajo, vendar znajo bit ZELO uporabni.

Sicer pa hungarian notation meni osebno ni vsec. Sploh pa ne za lokalne variable. Ce ne ves kasnega tipa je variabla, pol ne ves niti kaj pocne v tisti kodi ;) (moje osebno mnenje, nekateri ga kar veselo uporabljajo).

Pa za funkcije imam tudi raje old-school imena funkcije file_check_integrity() namesto FileCheckIntegrity().

Sicer pa verjetno je to stvar navade ... tisti ki, pridejo iz Windows okolja imajo najbrz raje xyzCapitalizeFunctionsNames(), Unixasi pa najbrz raje underscored_functions_names()... kdo ve ;)

Aja se nekaj. NIKOLI se v Cju ne uporablja // za komentarje, ceprav jih VC pozre!!

Drugace pa tisti ki delate v Linuxu (oz. s katerimkoli GCC compilerjem), ni slaba praksa ce si vklopite cim vec warningov(-ansi -pedantic -Wall -W -O).

Saj tam med

goto _EXIT_
}

in

_EXIT_:

manjkajo se ...

Mar ne? Zakaj bi sicer goto exit? ;)

kopernik:

Pri exception handlingu pojdi še korak dlje in išči več exceptionov na enkrat.

String nizNiSt = "tole pa ni stevilo";
String nizVenArray = "presegli smo okvirje arraya";
try  
{
    int number = Integer.parseInt(niz);
    b = a[number];
} 
catch(Exception e) 
{
    if (e instanceof NumberFormatException)
      System.out.println("Napaka pri konvertiranju stevila:\t" + niz);
    else if (e instanceof ArrayOutOfBoundsException)
      System.out.println("Napaka pri dostopu do arraya:\t" +nizVenArray);
}

Da bigwhale:)

Drgac je pa se ena varianta da uporabljas normalne returne, brez goto-jev in s cleanupom.. to s __try in __finally

Madžarska notacija pri programiranju kakšnih čudes z win32 API je skleda polna smeha.

Tudi drugače to ni nujno najboljša pot. Če recimo spremeniš tip globalne spremenljivke takoj nastane packarija, oziroma je kodo kanček težje vzdrževati. Takisto je nesmiselna pri kodiranju v kakšnem skriptnem jeziku, ki nima tako rigidno zastavljenih podatkovnih tipov.

To je res, čeprav ne tako drastično, ker kljub vsemu nimaš na voljo polnega obsega operatorjev za poljubni tip. Po drugi strani se pa ponekod ne moreš izogniti skakanju med tipi (recimo kakšne inicializacje z null)

Saj moras, recimo std::map<std::string, std::string>::const_iterator

Mislim, da je ta tema "dokaz", da c/c++ sux. Java kolikor stvari zadane, jih se vec zafrkne (negarantirani finalizerji, zelo svohen sistem tipov, ...). C# 2.0 se nisem prestudiral, ampak dvomim v kak velikanski napredek. Koliko casa bomo se obsojeni na jezike, ki uporabljajo znanje iz 60/70-tih?

Hotel sem reci, da zadnji krik mode c# nima nic vec (kvecjemu manj), kot jeziki iz '60/'70. LISP, smalltalk, ML, prolog, anyone?

P4 in AMDji so v bistvu zive umetnine, prakticno noben ni verjel, da se bo dalo z x86 naredit tako hitre procesorje. Splosno gledano so celo med najhitrejsimi nasploh. Edino poraba stroma je porazna, kar pomeni da niso uporabni za zelo velike clustre.

spodoben editor ima tudi replace funkcijo...

kaj ima to veze z gnilimi jajci? Priporocam da brises svoj post, ker je off-topic.

hatch:
Bom svojega zbrisal :-)

Ampak sedaj bi moral tudi tvojega. Ker klikanje po errorjih tudi nima nič s stilom kodiranja ... vendar ga ne bom. Upam, da bo tako volk sit in koza cela (zgleda da se vrtiva v začaranem krogu). Za naprej pa priporočam uporabo teme Pritožbe.

Se ne dogaja.

Če ti tako rečeš. Sedaj bom mirno spal in lahkih prstov zapisal

m_lpwszErr

Na pritozbe sem pisal ze nestetokrat.. pa tudi tam brisete moje kritike. Tako da je vseeno.. ali napisem tu in tu zbrisete.. ali pa tam, in tam zbrisete. Zal.

m_lpwszErr
lol? Si resen?
ne vidim zakaj bi to kdajkoli uporabil. Se manj pa zakaj bi tip take spremenljivke spreminjal.

Ampak recimo da imas tak program..

LPWSTR m_lpwszErr;
Logika mi pravi da bi to recimo hipoteticno spremenil na..
LPSTR m_lpszErr;

To pomeni da moras povsod kjer pises v to spremenljivko dodati, oz. odstraniti _T()
In vsak ne-neumen programer bi napisal zato MACRO. In tako je ta spremenljivka dostopana iz samo enega mesta. Oz.. se tam kjer jo beres. Problem spremeniti ime? Ne.

In ne pozabi... s stringi se error handlinga ne dela nikoli! Sele na koncu, ko zelimo izpisati errorje, se konvertirajo error kode v stringe s pomocjo katalogov.

Sej ce programiras za windowse ne rabis error handlinga.. ;>

Ker očitno množično ni jasno, da je bil navedeni primer cinizem, oznanjam, da je bil primer m_lpwszErr cinizem. Upam, da mi ni treba razložiti še čemu je temu tako.

hatch: Okay, bom se enkrat, da bo jasno. Imas instaliranih 100+ klientov. Pa hoces upgradeat server (recimo bugfix, evo mogoce dodat kak nov error message). Preprosto moras poslat nek error od serverja do klienta v obliki texta, ker klient tistih dveh byteov ne razume. Recimo: kljub temu, da IE izpisuje zelo fensi error message-e, ko gre kaj narobe, preprosto ne mora uganit tega: "Hello folx, we are fixing server over weekend, you can send urgent mail to xyz@abc.com".

owca: meni je to jasno :)

Ok, IE primer je malo beden. Ampak ravno the point je, da imas za "isto" napako lahko razlicno razlago. Dovolis, da program vseeno nekako pohendla napako, imas pa boljso razlago poleg v messageu. Hec je v tem, da v kodi direktno sistematicno puscas cimvec informacije, pa ti ni potrebno spreminjati protokola zaradi tega. Spremembe protokola so pogosto nemogoce. Tisti opisi napak naj bodo user friendly, tako da ti jih ni sram pokazati tudi userju. Ja, lahko imas neke standardne message, samo clueful uporabniku (sploh pa tebi, ko te kdo vprasa za pomoc), pogosto nic ne pomagajo. Minimalizem je pa bolje prihraniti za IETF standarde, ne pa day-to-day kodo. Razen ce se gres embedded sisteme jasno :).

Pošiljanje sporočil namesto kod prek omrežja je najbolj potraten način, ki si ga lahko zamisliš. Širina je draga, pa še ničesar ne pridobiš.

Ma tudi jaz ne vidim velike omejitve v dolžini stringa. razen pri gprs klijentih je še potrebno optimizirat. ampak z veliko lažje je parsati cifro in preverjati pravilnost vnosa , kot pa kakžen niz znakov.oziroma parsanje je le še en moment več ,da povoziš buffer. z katalogi zelo enostavno vršiš kostumizacijo(internacionalizacija pa še kaj bi se našlo ). Keep it simple and stupid.