čtvrtek 16. prosince 2004

Návrh projektu - adresářová struktura

Právě se chystám na přepracování adresářové struktury jednoho z našich projektů. Po důkladné přípravě proběhne obrovský refactoring stávající projektové struktury, která již nevyhovuje potřebám projektu. Změna adresářové struktury projektu je pokaždé velice bolestivou operací, a to z několika důvodů.

  • Musí být provedena změna v struktuře source repository např. CVS
  • Musí být provedena synchronizace s touto změnou
  • Změna se musí otestovat na patřičné úrovni (Unit testy na úrovni kódu, validita na úrovni build scriptu atd.)

Veskrze se jedná o ne nepodstatné důvody, které kladou důraz na chirurgické provedení. Někdy se bohužel jedná o tak radikální řez, že musíme skalpel vyměnit za sekáč. Proto je lepší těmto problémům předcházet na začátku projektu. Na základě zkušeností s několika rozsáhlejšími (alespoň z mého pohledu) projekty, jsem stanovil několik kroků pro vytvoření stabilní adresářové struktury projektu.

Návrh strukturu projektu před prvním commitem

Adresářová struktura většiny projektů vychází z určitých zkušeností a zvyklostí. Pro získání zkušeností nám může posloužit předešlý projekt, prototyp projektu a nebo úplně jiný projekt, jehož struktura nás inspiruje. V kostce máme hrubou představu o tom, jak bude adresářová struktura vypadat. Nejhorším možný přístup představuje okamžitá synchronizace (akce kulový blesk) našich představ se source repository.

Doporučuji strukturu zdokumentovat, doplnit o detailnější komentáře a vytvořit její prototyp.

Zdokumentování struktury
\root directory
	|
	|-db
	|
	|-doc
	|	|-javadoc
	|	|-project
	|    	
	|-config	
	|	|-hibernate
	|     	| 	|-app    	
	|	|		|*.hbm.xml 
Seznam adresářů s popisem
Název Popis
root directory Kořenový adresář projektu
doc Adresář pro dokumentaci
javadoc Adresář pro dokumentaci k API
project Adresář pro dokumentaci k projektu
config Adresář pro konfiguraci použitých frameworku
Hibernate Adresář pro O/R mapovací soubory Hibernate. Mapovací soubory jsou dále členěny v rámci aplikace.
app Konkrétní aplikační adresář pro mapovací soubory Hibernate
*.hbm.xml Mapovací soubor Hibernatu ctí syntaxi *.hbm.xml

Jak je vidět, k propojeni struktury a komentářů nám stačí HTML. Takto zdokumentovaná struktura je základ, na kterém se dá úspěšně stavět. Navrhovaná struktura by měla odpovídat source repository, na druhou stranu je možné dokumentovat i adresáře, které nejsou přímo součástí source repository, ale k projektu se přímo vztahují. Například se může jednat o adresář pro výsledky unit testů nebo o build adresář.

Validace struktury

Vyberte si úzkou skupinu lidí (3 až 4) a předložte jí návrh struktury. Cílem je podchytit případné boty v struktuře a strukturu dále rozšířit, ne vždy totiž dokážete určit všechna specifika. Všechny změny zadokumentujte a vytvořte obraz této struktury. Nyní máte první bod, na kterém se dá stavět. Nezapomínejte, že dokument popisující adresářovou strukturu by měl být součástí projektové dokumentace resp. její část pro vývojáře.

Stanovte pravidla a určete správce

Určete jednoho člena projektu (správce projektové struktury), který bude zodpovědný za změny v projektové struktuře. Nastavte hranice, podle kterých se určí odpovědnost správce, například strukturu na hlavní úrovni může měnit pouze správce projektové struktury. Nastavit tyto hranice je většinou obtížné, můžeme si pomoci pravidlem, že všechny sub změny musí být posvěceny správcem. Sub změna je taková změna, která neovlivňuje další části projektu (build skripty, API apod.). Správce má za úkol, o všech změnách informovat všechny členy projektu, změny provádět a dokumentovat. Přes správce jdou také všechny požadavky na změny.

Oživte strukturu

Připravený obraz vytvoří správce projektové struktury v source repository a vývoj se může rozběhnout. Samozřejmě, že během vývoje narazíte na potřeby rozšíření nebo drobnější úpravy stávající struktury, ale prostředí je nastaveno tak, aby změny neměly tolik bolestivý dopad.