How to Semestrálka (nejen pro BI-PYT)
Tento návod vám má usnadnit tvorbu semestrálky, nebere si za cíl být tím jediným správným postupem. Spíš může pomoci vyvarovat se slepým cestám a ušetřit vám čas propátrávání již objeveného. Jako vzorový příklad si vezmeme jedno z nabízených témat: Webová aplikace s kvízy.
Členění a struktura kódu
Připravte si strukturu celé semestrálky. To je sice pěkné, ale co to znamená? Na začátku si rozdělíme si projekt na jednotlivé části (většinou není pěkné, rozumné, ani udržitelné, mít všechny soubory v root složce projektu). Pokud si nejsme jistí jak rozdělení provést, vytvoříme si Entity-Relation (ER) diagram, do kterého zaneseme hlavní komponenty aplikace a jejich vzájemné vztahy. Můžeme též prozkoumat architekturu Model View Controller (MVC) a převzít základní koncept, nebo se alespoň inspirovat.
Po rozdělení na jednotlivé entity, může vypadat adresářová struktura např. takto:
Ve složce gui jsou zdrojové kódy, které například řeší (re)rendering jednotlivých komponent, funkcionalitu tlačítek, přeškálování okna, zvuky, atp..
Složka src slouží pro vlastní logiku aplikace. V src vytvořím soubory quiz.py, question.py, answer.py, ve kterých se bude implementovat samotná logika. Pokud by došlo k tomu, že by existovalo například více typů otázek (multichoice, singlechoice, otevřená otázka, číselný vstup, atd..), lze to vyřešit vícero způsoby.
Jeden takový způsob je, že logika otázky bude řízená nějakým přepínačem, jakožto typem otázky, nebo lze rozdělit implementaci podle typu pomocí dědičnosti. Tím pádem budu mít základní implementaci třídy, kterou budu v ostatních typech dědit (ale lze to také řešit například pomocí tzv. Factory method patternu). Tyto třídy mohou být všechny v 1 zdrojovém souboru question.py, nebo lze namísto app/src/question.py vytvořit submodule. To může vypadat následovně:
Třídy v multi_choice.py a text_input.py obě dědí ze třídy v soubory base.py
Varování:
! Pozor na Relativní importy !
V souboru multi_choice.py je lepší importovat třídu z base.py jako from app.src.question.base import BaseQuestion, nikoliv jako from ..base import BaseQuestion.
Verzujeme s GITem průběžně (nebo aspoň ex-post členíme commity)
Rozhodně není příjemné po celém dni zjistit, že jste díky chybě a malé velikosti paměti historie v IDE přišli o nějakou část kódu. Ať už kritickou, nebo ne, je to nepříjemné a dá se tomu jednoduše předejít verzováním. Internet je toho plný a stačí opravdu základy.
Testy
- Probírají se na 10. cvičení Link na notebook
- Opět pozor na relativní importy
- Bacha na spouštění z CLI vs IDE (IDE často modifikuje na pozadí při spuštění PYTHONPATH) a při spuštění testu z CLI to pak nefunguje. Je tedy nutné ověřit, že vám to z CLI bude běhat.
- Testujte průběžně při vývoji. Klidně můžete využít Test-driven Developement
- Nechte si IDE spočítat Code coverage a vyhoďte nepoužívané kusy kódu. Ať minimalizujete riziko chyby a nepíšete testy pro mrtvé kusy kódu.
- Testuje všechny podstatné části kódu - od přidání multichoice otázky, přes vykreslení přihlašovacího formuláře, po zpracování parametrů příkazové řádky. Pokud si nejste jistí, zda třířádkovou funkci má smysl testovat, tak pro ni test určitě napište.
- Spousta věcí se testuje blbě, zvlášť když nemáte kód dobře členěný, když máte různé parametry zadrátované a najednou nejde do metody podat treba jinou cestu k souboru s konfigurací apod.
- Je tedy zcela v pořádku, když zjistíte, že aby šel test dobře udělat, tak musíte kód aplikace upravit. A tak to hned udělejte!
- Parametrizujte testy, využijte fixtures, mockujte.
- Může vám je spouštět CI na gitlabu plně automaticky…
Report
- Vše podstatné je na ZDE
- Zapomeňte na fráze jako: “Cíle práce byly naplněny.” Zvláště, když je tam neuvedete. 🙂
- Nechte to po sobě před odevzdáním ještě přečíst někoho dalšího. Víc očí víc vidí a často vám první čtenář může říct, čemu nerozumí. Nejspíš jste to špatně vysvětlili.
- Citujte korektně, jak se to má dělat, když se to naučíte teď, jako když najdete u bakalářky/diplomky.
- Když vkládáte grafy/tabulky/obrázky, přizpůsobte rozlišení (5 MB BMP rastr velikosti 5×5 cm je fakt zlo).
- Vzpomeňte si na existenci vektorové grafiky.
- Popisky os grafu nejsou zbytečnost, musí být čitelné.
Konfigurace
Často se setkáte s tím, že ve vaší aplikaci používáte nějakou konstantu několikrát na jednom místě a najednou jí potřebujete změnit za jinou. V tu chvíli jsou jen dvě možnosti - buďto jí máte hárdcoded jako hodnotu (např. area = r*(3.14*3.14)) a protože chcete lepší přesnost, jste nuceni jí přepsat na každém místě, nebo použijete nějakou formu konfigurace - .py soubor, který si naimportujete, nebo knihovnu která parsuje nějaký konfigurační soubor (.yaml, .conf) a následně použijete hodnoty z něj (např. area = r*(config.const.PI**2)). Změny potom děláte v konfiguračním souboru a je to přehlednější.
Konfigurovat se spousta věcí - např. cesty k souborům a jejich názvy nebo konstanty. Konfiguračních souborů může být víc.