mamweb/docs/zapisy/2021-12-06-testovani_dokume...

# 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 (`seminar.utils.roman_numerals`) i false negatives (`seminar.models.tvorba.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.
Přidán zápis o zkrášlování kódu (testy, doku, CI, code review, …) Je v náhodné složce, ale někde být musí :-) 3 years ago			`# 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 (`seminar.utils.roman_numerals`) i false negatives (`seminar.models.tvorba.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.`