mamweb/docs/zapisy/2021-12-06-testovani_dokumentace_codereview.md

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

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, 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 (https://mam.mff.cuni.cz/wiki/Web_user/Dokumentace, 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.