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í :-)
This commit is contained in:
Pavel "LEdoian" Turinsky
parent
d60d2eee6e
commit
5a6a2eee93
1 changed files with 173 additions and 0 deletions
173
docs/zapisy/2021-12-06-testovani_dokumentace_codereview.md
Normal file
173
docs/zapisy/2021-12-06-testovani_dokumentace_codereview.md
Normal file
|
|
@ -0,0 +1,173 @@
|
||||||
|
# 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.
|
||||||
Loading…
Reference in a new issue