Hlavní navigace

Hackerská etiketa (2)

Karel Kulhavý 25. 3. 2004

Vývoj svobodného softwaru probíhá specifickým způsobem za současné úzké spolupráce vývojářů a uživatelů. První díl pojednával o pohledu ze strany uživatele, v tomto dílu se na problematiku podíváme z hlediska vývojáře.

Z hlediska vývojáře

K programu by měla být dokumentace. A mělo by být jasné, jaká verze dokumentace patří k dané verzi programu a co ještě je dokumentace k programu a co jsou nějaké nezávazné úvahy nějakých třetích uživatelů. Pokud toto není splněno, snadno se uživatel dostane do stavu, kdy není schopen v používání programu přímočaře pokračovat.

Dokumentace k programu by měla být v nejjednodušším formátu, v jakém je to možné. Pokud instalujeme něco na routeru, kterému funguje pouze textový režim nebo vzdálený přístup po ssh po modemu a dokumentace je ve formátu Word, spláčeme nad výdělkem.

Dokumentace se hodí i samotnému vývojáři. Zprvu to vypadá, že žádná potřeba nebude. Ale když se vývojář k projektu vrátí po delší době, zoufale zjišťuje, že si není schopen vzpomenout na spoustu detailů, které tenkrát vypadaly, jako že jsou nade vše jasné.

Taktéž by ke čtení dokumentace neměl být potřeba proprietární program. Pak by byla znehodnocena sama původní idea svobodného programu. Stejně tak by k přečtení dokumentace nemělo být potřeba instalovat mnoho složitého programového vybavení. Stalo se mi, že jsem narazil na oficiální dokumentaci k jádru Linuxu v DocBook. Příslušné konvertory měly haldu závislostí, některé z nich se nedaly zkompilovat (syntaktická chyba při kompilaci) a dokonce jsem nainstaloval zrovna ten druhý program „jade“, než který to chtělo (nepsalo se tam bližší určení, který jade). Problém jsem řešil s vývojáři na linux-kernel a ani společnými silami se nepodařilo dosáhnout toho, abych si dokumentaci přečetl :)

K programu by měla být kromě dokumentace přibalena i specifikace (popis rozhraní), jejíž součástí jsou podmínky postačující k přeložení programu. Pokud program vyžaduje knihovny, mělo by se napsat, kde se tyto knihovny vezmou. Nestačí napsat jméno balíčku, protože balíčky se distribuci od distribuce liší a někteří si i kompilují programy sami. Pokud už jméno balíčku uvádíme, nesmíme zapomenout, že existují balíčky -devel, které obsahují hlavičkové soubory. Jsou potřeba, když se program, který na balíčku závisí, kompiluje. Je třeba napsat deterministický návod, jak požadované knihovny do systému nainstalovat, nezávislý na používané distribuci.

Součástí průvodní dokumentace ještě před tím, než se program začne kompilovat, by měl být kontakt na autora a návod, jak hlásit chyby. Je možné, že uživatel nalezne chybu v dokumentaci už na začátku nebo při kompilaci programu (to je velmi časté), a když bude muset tyto údaje složitě hledat, existuje riziko, že chybu odloží a pak si už nebude pamatovat, jak ji vyvolal.

U každého zdrojáku se začíná souborem README. Zde by mělo být napsáno vše, co uživatel bude potřebovat:

  • Potřebné knihovny, u každé algoritmus, jak ji dostat na systém. Součástí algoritmu může být samozřejmě odkaz někam jinam (pozor, aby URL nebylo deadlink), kde se to člověk dočte.
  • Jak instalovat (často se dává do samostatného souboru INSTALL)
  • Jméno a kontakt na autora
  • Jak hlásit chyby
  • Kde je dokumentace k programu („návod k použití“) (například u balíčkovacích distribucí mi chybí, že nainstaluju program např. příkazem emerge jménoprogramu, ale nedozvím se odkaz, kde začíná návod k programu). Stejně jako se k výrobkům přikládá návod, je vysoce užitečné mít ohraničený návod k programu, který je možno mít i offline (co když uživatel nemá doma Internet?). Zde má velkou výhodu Linux From Scratch – člověk se často naučí používat program ještě dříve, než ho zkompiluje :) LFS obsahuje popis, co přesně dělají důležité instalované soubory.
  • Licence. Aby uživatel věděl, za jakých právních podmínek program může používat.

Projekty často mívají webovou stránku, ale není to pravidlem. Pokud stránka existuje, je dobré na ni odkázat v README. Na webovou stránku je vhodné umístit nějaký dobře viditelný startovací bod, kde by měli začít uživatelé, kteří jsou zde poprvé (typicky následuje specifikace projektu a pak návod k instalaci). Jinak nově příchozí, co chtějí jen program nainstalovat, mohou dlouhou dobu bloudit, svedeni falešnými stopami.

Ne každý se při čtení webové stránky hodlá s projektem podrobně seznámit. Pokud je projekt požadován jako závislost k něčemu jinému a uživatel nepoužívá distribuci, zajímá jej pouze krok po kroku jednoduchý návod, jak program nainstalovat, současně s částí dokumentace, kde se vysvětlují rozhodnutí, která se při instalaci dělají.

Na stránkách často chybí specifikace, což jsou co nejjednoduššeji vyjádřené charakteristiky, které umožňují rychle zjistit, zda se program bude moci „zapojit“ do prostředí tak, jak zamýšlí uživatel. Pokud nejsou k disposici, může se např. stát, že uživatel se bude měsíc seznamovat se Sambou, aby pak nad pokročile nainstalovaným Samba serverem zjistil, že jej nelze použít, protože PDC/BDC replikace nefunguje ve verzi Samba PDC a NT4 BDC a nějaké okolnosti ho nutí, aby BDC byl NT4 server. Specifikace by měla obsahovat:

  • Nutné podmínky pro správný provoz programu – např. informaci, že jádro musí být řady 2.6 a ne 2.4 a nižší, nejlépe i potřebné knihovny
  • Co program nabízí za funkce a specifikace jednotlivých funkcí
  • Co v programu má chodit ale nechodí, jaké má momentálně bugy

Je také vhodné dbát na to, aby program, když vypisuje chybovou hlášku, poskytoval co nejvíc informací. Dobré je uvádět jméno programu, který chybu hlásí, a příčinu chyby. U Windows jsem viděl hlášku „unexpected network error“. To je příklad, jak by hláška vypadat neměla. Naopak „ssh: connection reset by peer“ je dobrá hláška, protože uživatel se může podívat do specifikace protokolu TCP a vyhledat si, co v tomto kontextu přesně znamená pojem „reset“. Chybová hláška by obecně měla maximálně usnadňovat diagnostiku a „vyšetřování“, co se stalo.

První chybové hlášky, se kterými se uživatel vůbec může setkat, se mohou vyskytovat při běhu skriptu configure. Typicky proto, že chybí nějaká knihovna. Je dobré, když program v takovém případě oznámí, jaká knihovna a které verze jsou potřeba. Úplně nejluxusnější je, když přímo vypíše, kde se dá tato knihovna získat. Také není dobré, když ./configure nepřijde na nepřítomnost knihovny, knihovna není napsána v README jako předpoklad pro kompilaci programu a make potom na tom spadne. Nejlepší je mít specifikaci potřebných knihoven v README i test v configure.

Program nemusí nutně používat autoconf, automake a spol., ale protože přenositelnost je vlastnost v hackerském světě velmi oceňovaná, spousta programů tyto nástroje používá, protože i když mají svá omezení, byly právě za účelem usnadnění přenositelnosti vyvinuty.

Dle mého názoru dobrým příkladem, jak se vydávají programy, je projekt GNU. Zdrojáky vždy obsahují README a INSTALL a obecně se kultura jednotlivých projektů v rámci projektu GNU udržuje na určité standardní úrovni.

Existuje rozdíl mezi svobodným softwarem a softwarem s otevřeným kódem (open source). Může existovat software, který má otevřený kód a není svobodný, ale ne naopak. Přesně se tyto pojmy definují v textu od Richarda Stallmana Why „Free Software&quot is better than "Open Source“.

S hackerskou etiketou se člověk setkává typicky v oblasti svobodného software. Do oblasti open source může spadat i například program uvolněný určitou firmou, kde je zdrojový kód k dispozici, ale dotyčná firma nemá žádný zájem na symbióze mezi tvůrcem programu a jeho uživateli. V takovém případě výše uvedený přístup nemusí platit.

Našli jste v článku chybu?

27. 3. 2004 13:30

uživatel si přál zůstat v anonymitě

ide, pretoze pouziva automake ;)

27. 3. 2004 7:30

Martin Kysela (neregistrovaný)

A jak to vypada, kdyz teces? ;-))

Lupa.cz: Slevové šílenství je tu. Kde nakoupit na Black Friday?

Slevové šílenství je tu. Kde nakoupit na Black Friday?

DigiZone.cz: Česká televize mění schéma ČT :D

Česká televize mění schéma ČT :D

Podnikatel.cz: Přehledná titulka, průvodci, responzivita

Přehledná titulka, průvodci, responzivita

Podnikatel.cz: K EET. Štamgast už peníze na stole nenechá

K EET. Štamgast už peníze na stole nenechá

Podnikatel.cz: Vládu obejde, kvůli EET rovnou do sněmovny

Vládu obejde, kvůli EET rovnou do sněmovny

Lupa.cz: Co se dá měřit přes Internet věcí

Co se dá měřit přes Internet věcí

Podnikatel.cz: Prodává přes internet. Kdy platí zdravotko?

Prodává přes internet. Kdy platí zdravotko?

120na80.cz: Pánové, pečujte o svoje přirození a prostatu

Pánové, pečujte o svoje přirození a prostatu

Vitalia.cz: Tesco: Chudá rodina si koupí levné polské kuře

Tesco: Chudá rodina si koupí levné polské kuře

Vitalia.cz: Láska na vozíku: Přitažliví jsme pro tzv. pečovatelky

Láska na vozíku: Přitažliví jsme pro tzv. pečovatelky

Měšec.cz: Finančním poradcům hrozí vracení provizí

Finančním poradcům hrozí vracení provizí

Lupa.cz: Není sleva jako sleva. Jak obchodům nenaletět?

Není sleva jako sleva. Jak obchodům nenaletět?

120na80.cz: Rakovina oka. Jak ji poznáte?

Rakovina oka. Jak ji poznáte?

Lupa.cz: Proč firmy málo chrání data? Chovají se logicky

Proč firmy málo chrání data? Chovají se logicky

Lupa.cz: Babiš: E-shopů se EET možná nebude týkat

Babiš: E-shopů se EET možná nebude týkat

Vitalia.cz: Jsou čajové sáčky toxické?

Jsou čajové sáčky toxické?

Lupa.cz: Avast po spojení s AVG propustí 700 lidí

Avast po spojení s AVG propustí 700 lidí

Vitalia.cz: Chtějí si léčit kvasinky. Lék je jen v Německu

Chtějí si léčit kvasinky. Lék je jen v Německu

Podnikatel.cz: Na poslední chvíli šokuje vyjímkami v EET

Na poslední chvíli šokuje vyjímkami v EET

120na80.cz: Bojíte se encefalitidy?

Bojíte se encefalitidy?