Pravidla pro psaní zdrojových souborů

Title Pravidla pro psaní zdrojových souborů
Author Richard Michalský
Date 1.12.1998
Reference kralik@mail.kolej.mff.cuni.cz
File docs/pravidla.html
Project KTTV

Tento dokument shrnuje několik pravidel pro psaní zdrojových textů domluvených na schůzce projektu 24.11. Platí hlavně pro interface objektů, ale bylo by vhodné je v rámci možností dodržovat i uvnitř kódu (jeden nikdy neví, po kom se v tom bude muset hrabat).

Identifikátory

Všechny identifikátory budou anglicky, jednotlivá slova jsou oddělena velkým počátečním písmenem, nepoužívají se podtržítka. Jména tříd a typů začínají velkým písmenem (ReallyWeirdType), jména funkcí a proměnných malým (prettyUglyFunction). Konstanty jsou celé velkým písmem(ANOTHERBLOODYCONST). Identifikátory globálních proměnných a typů začínají jedno- nebo dvoupísmenným prefixem odděleným podtržítkem, který určuje ke které části programu identifikátor patří, tj. např. sl_SomeGlobalClass nebo tx_veryImportantVariable. Na lokální proměnné se tato pravidla nevztahují striktně, řídící proměnná cyklu se samozřejmě nemusí jmenovat myVeryLocalCounter, když stačí a.

Používané konstrukce

Konstanty budou definovány buď jako prvky výčtového typu (jedná-li se o výčet možností) nebo pomocí direktivy #define, pokud konstanta udává nějakou konkrétní hodnotu. Konstantní proměnné se používat nebudou, na druhou stranu se doporučuje v deklaracích co nejvíce používat konstantní parametry funkcí, tj. ty, které ve fci nejsou měněny, např.:

int strlen(const char *)
a konstantních metod tříd (metody, které nemění prvky třídy - dají se používat i u konstantních objektů). Deklarace vypadá takto:
int SomeClass::getSize() const
Jako odkazy na objekty se používají hlavně ukazatele, reference jen v obvyklých případech (copy constructor), member pointery pouze pokud to bude nezbytné (a v komentářích to výslovně uvést). Poslední obecné previdlo ohledně identifikátorů je deklarace všeho druhu co nejvíce schovávat, včetně použití privátních členů tříd, zahnízděných datových typů (sic!), co nejvíce lokálních proměnných, atd. Po domluvě jsme se také (přestože mnozí ani neví, jakému nebezpečí byli vystaveni) rozhodli nepoužívat šablony ani vlastní ani se STL (standart template library) a všechny potřebné datové struktury (seznamy, fronty, zásobníky) si napsat sami. To předpokládá zjistit ve fázi návrhu, které struktury jednotlivé algoritmy vyžadují a pak je implementovat. Tady se dá s výhodou využít standartní předek všech objektů, který zajistí, aby struktury uměly manipulovat se všemi objekty programu

Headery a zdrojové soubory

Jak hlavičkové, tak vlastní zdrojové soubory budou obsahovat vždy standartní hlavičku (nejspíš okopírujeme tu ze zdrojáků wxWindows), pro vyplnění položek se dá s výhodou použít expanzní řetězce cvs ($author$, $revision$, ...). Praktický důsledek je, že autor nemusí do hlavičky nic vyplňovat, stači ji zkopírovat na začátek souboru a cvs to udělá za něj (praví teorie). Ke každému zdrojovému souboru existuje jeden hlavičkový (nejlépe stejného jména), kontrolovaný na "nainkludování" asi takto:

#ifndef __<jméno headeru>_IS_INCLUDED__ //například
#define __<jméno headeru>_IS_INCLUDED__

<tělo headeru>

#endif
Správné deklarace globálních proměnných příslušného zdrojového souboru se dosáhne použitím následující konstrukce:

//header

//deklarace globálních proměnných
_EXT_ int theAnswer
#ifndef _EXT_ //pokud potřebuji i přiřadit hodnotu
= 42
#endif

//zdroják

#define _EXT_ external //kromě souboru obsahujícího fci main
#include <header1>
//...

Pěknou třešničkou by bylo zdrojové texty komentovat!

Na závěr ještě navrhuji vytvořit pro headery a zdrojové soubory kostru.