Jak na pro­jek­ty v ja­zy­ce C

© Damig, 2004 – 2016
Koncept

Pomoc! Kde najdu dokumentaci?
Druhy dokumentací

Než se podíváme, kde a jak hledat informace, musíme si ujasnit, co konkrétně chceme hledat. Někdy se vám totiž může stát, že sice najdete v zásadě správné informace, ale budete zklamaní z toho, jakou formou jsou podány. Když totiž stojíte o rychlé nalezení konkrétní specifické informace, jako například o počet a význam parametrů nějaké knihovní funkce, může vám být na obtíž hromada populárně naučného povídání okolo. A opačně, když stojíte o vysvětlení, jak funguje práce s pamětí, je nepříjemné to dedukovat ze suchého popisu funkcí, které se tím zabývají. No a nakonec často víte, co chcete dělat (např. alokovat paměť), ale nevíte, jaké všechny funkce jsou k dispozici, abyste mohli vybrat tu nejlepší pro řešení vašeho problému. Pak potřebujete nějaký šikovně udělaný rejstřík funkcí orientovaný podle témat.

Existují různé druhy dokumentací a zdrojů informací pro programátory. Nás budou zajímat zdroje zabývající se standardní knihovnou funkcí jazyka C, dále pak zdroje popisující samotný jazyk a nakonec i použití různých programátorských nástrojů.

Rozdělení podle účelu

Uživatelský manuál

Uživatelský manuál obsahuje informace o programech nebo knihovnách z uživatelského hlediska. Poradí vám, jak je nainstalovat, nastavit a zprovoznit. V případě programů vám ukáže, s jakými parametry jdou spouštět, pokud jde o programy s GUI, popíše vám strukturu menu. Je to podobné tomu papíru, co vám jako první vypadne z krabice, když si koupíte novou ledničku. Při hledání na internetu použijte klíčová slova user manual a guide.

Slušně napsané programy mají uživatelský manuál zabudovaný v sobě. U programů s GUI jej najdete v menu Nápověda (Help), u programů s CLI můžete vyzkoušet spuštění s přepínači -h, --help nebo /?. V unixových systémech je kromě toho zvykem poskytovat ke každému programu manuálovou stránku zobrazovanou příkazem man jmenoprogramu (viz dále).

Tutoriál

Tutoriál poskytuje základní představu o hlavních rysech jazyka nebo knihovny, základních konstrukcích a oblastech použití. Obvykle jde o souvislý text, tématicky členěný do kapitol. Jednotlivé funkce jsou popisovány postupně podle toho, jak se to hodí k vysvětlovanému tématu, často na příkladech. Specifickým příkladem tutoriálu může být učebnice programovacího jazyka. Tento dokument se také dá pokládat za tutoriál.

Je důležité vědět, že v tutoriálu se při hledání konkrétní informace musíte prokousat množstvím souvislého textu. Je to dobrý výchozí bod, když o tématu vašeho zájmu (alokace paměti, zpracování vstupu a výstup, atd.) potřebujete získat všeobecný rozhled. Konkrétní funkce zde zřejmě budou zmíněny, možná zde najdete i ukázky kódu, ale detailnější informace o daných funkcích pak hledejte spíše v referenčním manuálu.

Referenční manuál

Toto je to pravé místo kam jít, když víte přesně, co hledáte. Obsahuje vyčerpávající popis všech knihovních konstant, proměnných, funkcí a jejich parametrů (nebo příkazů jazyka, pokud jde o manuál k jazyku), ale i kapitoly věnující se obecnějším tématům, které zasadí použití jednotlivých funkcí do vzájemného kontextu.

Referenční manuál může mít strukturu podobnou tutoriálu, tedy kapitoly se souvislým textem. Na rozdíl od tutoriálu ale bývá mnohem přesnější a kompletnější. Druhou možností je referenční manuál organizovaný jako seznam konkrétních položek, v našem případě funkcí a datových typů, kde u každé položky jsou uvedeny všechny relevantní informace, které se k ní váží a to i za cenu, že některé informace jsou uváděny duplicitně. Výhodou je, že se v takovém manuálu dobře vyhledává podle jmen funkcí. Příkladem takového manuálu jsou manuálové stránky v unixových systémech.

Třetí možností je tutoriál kombinující prvky obou předchozích typů, tedy jak obecné kapitoly, tak seznam konkrétních položek. Příkladem takového manuálu jsou GNU info stránky knihovny libc nebo jejich online podoba.

Znáte-li tedy jméno funkce, najdete zde vyčerpávající a přesný popis parametrů, návratové hodnoty a chování v různých situacích, včetně reakcí na různé chybové stavy. Protože knihovna obvykle obsahuje funkce vyhovující různým verzím standardů jazyka spolu s funkcemi, které jsou bonusovým rozšířením výrobce, poskytuje manuál u každé funkce i výčet standardů, kterým daná funkce vyhovuje. Kromě toho u každé funkce obvykle najdete i seznam příbuzných funkcí, zabývajících se stejnou tématikou.

Normy

Kromě zmíněných typů dokumentace se ještě můžete setkat s normami jazyka C a jeho knihoven, respektive s jejich náčrty (angl. draft). Obsahuje precizní a jednoznačné informace a používá matematické formalismy pro popis syntaxe jazyka. Slouží především pro výrobce překladačů a knihoven. Pro běžného uživatele to obvykle není ten nejlepší zdroj informací, ovšem nikoli kvůli nedostatku informací, ale jejich přílišnému množství.

Jak poznat relevantní zdroj

Programovací jazyky i jejich knihovny procházejí vývojem. Aby bylo možné vytvářet programy, které jsou přenositelné, jsou různé verze jazyka a knihoven popsány pomocí norem, které se každých několik let aktualizují.

Přenositelností mám na mysli, že jednou napsaný a odladěný program bude na úrovni zdrojového kódu beze změn použitelný na různých operačních systémech (opravdu jde psát programy, jejichž kód je totožný pro Linux, jiné unixové systémy i Windows). Zároveň je takový program přeložitelný na překladačích od různých výrobců. Bez norem jazyka, které dodržují jak výrobci překladačů, tak výrobci operačních systémů, ale i samotní programátoři, by něco takového nebylo možné.

Chcete-li psát přenositelné programy, a zejména pokud s programováním začínáte, tak byste to měli chtít, protože si tím značně zjednodušíte život, měli byste si v dokumentaci k jednotlivým knihovním funkcím všímat, jaké normě jazyka daná funkce vyhovuje. Nejdůležitější jsou normy ISO, ANSI, případně POSIX. Například v manuálových stránkách si těchto zkratek všímejte v kapitole CONFORMING TO, která popisuje, jakým normám dané funkce vyhovují.

ISO je označení mezinárodní normy. V současnosti nejnovější verzí jazyka C je ta, která je popsaná normou neformálně označovanou jako ISO C11, která byla schválena v roce 2011 (její oficiální označení je ISO/IEC 9899:2011). Předchozí verze z roku 1999 byla značená ISO C99. Použijete-li ve svém programu pouze funkce, které jsou v dokumentaci označeny jednou z těchto zkratek, nebudete mít problémy s přenositelností.

ANSI je označení standardů používaných v USA. Zkratkou ANSI C je obvykle označována starší verze jazyka C z konce 80. let 20. století. Tato norma byla později přejata i ISO. Uvidíte-li někde zkratky ANSI C, ISO C89, ISO C90, jedná se o tutéž verzi jazyka C a jeho knihoven.

Poslední významná zkratka, která vás může zajímat je POSIX jde o normu popisující unixové systémy. Funkce patřící pod tuto normu jsou zároveň součástí rozhraní unixového systému. Funkce podle standardu ISO C zároveň spadají do normy POSIX, opačně už to platit nemusí.

Pokud se dokumentace, kterou používáte odvolává na tyto normy, je pravděpodobně bezpečné ji používat. Zdroje, které normy jazyka neřeší, nepoužívejte. Nemáte u nich jistotu, co vlastně popisují.

Online zdroje

Jste-li neustále připojení k internetu, najdete tam samozřejmě všechny důležité informace. Musíte si ovšem dávat pozor na zastaralé zdroje. Abyste nemuseli dlouho tápat, nabízím dva bezpečné zdroje informací o knihovnách jazyka C.

Referenční manuál knihovny GNU C

Jde o oficiální manuál pro implementaci knihovny jazyka C z projektu GNU. Jeho obsah odpovídá info stránkám v Linuxových systémech. Najdete zde dokumentaci jak ve formátu HTML, tak PDF knihu i samotné info stránky. Chcete-li v této dokumentaci najít informace ke konkrétním funkcím a datovým typům, spíše než k obecným tématům, najděte si v obsahu kapitoly Function Index a Type Index.

cppreference.com

Jde o velmi pěkně zpracovaný manuál k jazykům C a C++ podle posledních norem těchto jazyků. Kromě popisu knihoven obsahuje i popis syntaxe obou jazyků. Popis jednotlivých funkcí je stručnější než například v manuálových stránkách, což ale přispívá k lepší čitelnosti. Navíc nabízí množství ukázek kódu.