# Postup zkrášlení kódu M&Mího webu ## Obecně o webu - Python, Django, spousta nějakých rozšíření, frontend HTML + CSS + trocha JS - Velké břímě historie, kterou nejspíš nechceme zahodit - Změny v M&M někdy dost zamotají potřebný kód (tituly) - Občas je potřeba dělat opravy rychle ## Aktuální stav - Zběsile zbastlený kód - „Co je to ‚single responsibility principle‘?“ ☺ - Dost netriviální množství objektů a jejich vazeb - Dost možná do velké míry inherentní složitost - Webaři aktuálně relativně zběhlí v programování (ale je potřeba myslet na to, že to tak být nemusí) - Webaři stárnou (Jethro, Kristý, Anet) a mizí (Pavel, Káťa), je potřeba web připravit na předání - Kód je rozdělený mezi orgy a jeden „nerozumí“ tomu, co druhý napsal (musí to vyčíst z kódu, nezná souvislosti, …) - Noví orgové se aktuálně musí ptát, což je jim nepříjemné a nutí je umět formulovat dotazy ### Invarianty - Není to práce, ale zábava-ish → libovolný proces nesmí být (moc) na obtíž. - I malé nepohodlí je potřeba vyvážit relativně velkým přínosem - nebo dostatečně zřejmou vidinou budoucího pohodlí / minimalizace nepohodlí - Nejsme programátoři, spíš jsme bastlíři kódu (kteří znají rozumnou podmnožinu syntaxe Pythonu) - Zvlášť noví orgové - Nechceme cílit na mega-profi kód, je to nedosažitelný cíl - Nejspíš to do nějaké míry ubastlené bude pořád, ta míra závisí na zkušenosti aktuálních webařů - Nástroje nás nesmí moc mást. - Děláme to zadarmo jeden večer v týdnu - Vývoj jde pomalu, často pomaleji než vývoj knihoven - → kód se rozbíjí i sám - Běží to na Gimlim - Debian (old)stable → nemůžeme používat moc nové featury Pythonu - Aktuálně Python 3.7.3 - Webaři jsou náhodně vzniklá skupina lidí. - Různé nástroje, různé operační systémy - Nechceme vynucovat konkrétní metody, multiplatformní nástroje asi požadovat můžeme - Na serveru může běžet cokoliv, co tam jde rozběhnout - Kód by neměl být moc složitý / matoucí / kompaktní (?) - případně fakt hodně okomentovaný ## O co se snažíme - Zpřístupnit vývoj novým webařům - Umožnit chápání i cizího kódu co nejjednodušeji - Nevzít si s sebou implementační tajemství ~~do hrobu~~ pryč z M&Mka ```graphviz digraph "Závislosti věcí" { ss -> sdil -> doku -> cs; ss -> cit ->ref -> cs; ref -> nrt -> tst -> cs; sdil -> cr -> cs ss -> nrt; ss[label="Současný stav",shape=box]; cit[label="čitelný kód"]; cs[label="Cílový stav",shape=box]; ref[label="refactoring"]; nrt[label="nerozbít to"]; tst[label="testy"]; doku[label="dokumentace (vývojářská)"]; sdil[label="chápání kódu ostatních / stávajícího"]; cr[label="code review"]; nrt,sdil,cit[shape=hexagon]; tst,doku,cr[color=blue]; } ``` ## Code review Aktuálně: Pavel občas z rozmaru čte diffy; párkrát jsme zkoušeli [programovat v páru](https://mam.mff.cuni.cz/wiki/Web/Tipy/PairProgramming), je to relativně časově náročné. - Nevynucovat - Primární motivace je umožnit nějak vidět změny a případně k nim dávat komentáře, jak stylu „tohle mi není jasné“, tak i „tohle by chtělo přepsat“. - Chceme hlavně vytvořit příležitost ke čtení cizího kódu a seznamování se s ním (i v zájmu zaučování nových webařů) ### Názory - spíš post-hoc - Možná code-review toho, co jde na produkci - Chceme umět komentovat konkrétní řádky kódu - Gitea/gitlab? - Klikátko a barevný řádky a vyhledávání jsou fajn (gitlab, gitea) - Jethro: je fajn umět skočit na definici - Kombinace s CI - Pokud bude gitea v něčem nedostatečná, tak hrozí, že bude potřeba migrovat znovu, což je nepraktické - Gitlab je asi častější než gitea → je lepší názor si na to zvyknout __Závěr:__ Zkusíme to hodit do GitLabu (nejspíš veřejného\*), zavedeme pull-requesty do `master` větve, náhodně se budeme přiřazovat a používat ho nějak intuitivně. \*: Ve fakultním neumíme přidávat další uživatele, v KAMím zas možná není CI. ## Testy Aktuálně: pár testů na dohromady řádově 4 funkce, drobný pokus o TDD, jenž narazil na úskalí reálného světa. Lokální spuštění testů trvá relativně dlouho, nejspíš kvůli spoustě migrací. - Potřebujeme ověřit, že to funguje a že to _pořád_ funguje - CI? Coverage? ### Názory - PyTest je fajn - Testovat frontend? - Jethro: při nasazení by se mohly dělat screenshoty celých vybraných stránek přes Selenium (nebo obdobné) a hlásit rozdíly __Závěr:__ Backend testujeme PyTestem (`./manage.py test`), u frontendu výhledově zkusíme ty vizuální diffy a pak se uvidí, CI podle webového klikátka na code review. Bylo by dobré mít rozumná testdata, ať se nemusí mockovat moc věcí. ## Formát kódu Aktuálně: Jakýsi coding style zhruba existuje, není popsaný, šíří se lidovou slovesností. - Nesmí být striktně vynucovaný - Musel by být hodně nastavitelný - Nechceme mít kód plný `#NOQA: WTF42` - Nejspíš vždycky bude mít false positives (`tvorba.utils.roman_numerals`) i false negatives (`tvorba.models.Cislo.posli_cislo_mailem`) - Možná dobrý sluha, ale určitě špatný pán (also: špatná zkušenost ☺) - __Důsledek:__ Hrozí, že těch falešných varování bude moc, čímž to ztratí smysl úplně - Potenciálně by šlo aplikovat jen lokálně na změny? ### Názory - P: nemyslím si, že zvládneme mít „průhledný kód“ (dostatečně konzistentní kód, aby ho člověk přestal vnímat a spíš viděl myšlenky). - P: Kecadla do kódu trochu zavání větším peklem než užitkem (takže black a flake8 jsou ze hry); isort možná dává smysl; je otázka, jestli použít mypy, ale typové značky v kódu spíš chceme (zvlášť u věcí, které nejsou prostě django view – typicky utils.) - J: Divné (=Pavlovo) groupování importů je spíš matoucí, spíš moc nepomáhalo - P (doplněno zpětně): pydocstyle vynucuje PEP-257, který se možná tluče se sphinxem… - P (též zpětně): Možná by se mohl dát použít pylint, tomu jde aspoň vysvětlit coding style a nerazí tupě PEP-8, ale nastavovat ho je asi větší porod, než jak moc pomůže… __Závěr:__ Kecadla na formát spíš nechceme; isort by mohl být fajn, ale bylo by dobré mít rozdělené bloky „náš kód“, „standardní knihovna“ a „Django a další balíčky z PyPA“; u našeho kódu (utils, obecně ne-Django věci) chceme držet záměr (na úrovni dohody) psát signatury funkcí a v případě jejich přítomnosti se nechat varovat při porušení signatury. - P (večerní prokrastinace): Bandit vypadá, že hlásí jen strašně obvious věci by default, nepřijde mi jako moc úžasné vylepšení. Do CI možná dobrý ## Dokumentace Aktuálně: něco málo je na wiki (`/Web/`), občas má nějaká funkce docstring, obecně je toho málo ### Požadavky - Jedno autoritativní místo a dá se najít - Dostatečně „blízko“ kódu - nastavit mindset na psaní dokumentace „rovnou“? - Umožnit i obecný text, ne jen komentáře kódu (modulů, funkcí) ### Bonusy - Zajišťování konzistence s uživatelskou dokumentací - aktuálně wiki - Podpora i dalších jazyků (Vue, Javascript, CSS, možná django-templates) ### Názory - Jde to dělat sphinxem - Stínovlas by mohl vědět v CZ.NICu se sphinx jede. Případně zkusit zjistit, co umí jejich Akademie - Free-textová dokumentace (architektura ap.) má být nezávislá na dokumentaci konkrétního kódu, ale je fajn, když se to pak spojí dohromady, jde-li to. - Lepší, když se obojí dá dělat stejným nástrojem - Káťa má někdy pocit, že tráví spoustu času tím, že hledá který soubor vůbec upravit; to má v naší dokumentaci být. __Závěr:__ Zkusíme použít sphinx (z nedostatku vlastních zkušeností a kvůli jeho popularitě), když se nám to nebude líbit, tak budeme řešit dál. Bylo by fajn najít nějaký workshop, bude to rychlejší nalejvárna než číst dokumentaci. V krátkodobém výhledu stáhneme vývojovou dokumentaci z webu do repozitáře a zprovozníme někde automatické buildy (aby se dala číst jako člověk a ne jako stroj). ## Uživatelská dokumentace - K: Dělat ji ve spolupráci s těma uživatelema - P: Dávný Hedgedoc může případně sloužit jako základ osnovy - K: Dost možná nevíme, co bolí víc a co míň - Jethro: Musí být na wiki, jinak tím zmateme oržstvo __Závěr:__ Dokumentace bude na wiki (, výhledově možná ve stejné složce v dalších souborech), bude vznikat podle našich pocitů a dotazů od ostatních; výhledově bude schůzka na ukázání featur nového webu a tam se dosbírají náměty na to, co sepsat.