Best Practices pre štátny F/E

Bolo by fajn, mať pre štátne weby aspoň základný guideline v oblasti F/E — ak sa má do projektov zapájať mnoho developerov, firiem a rozličných prístupov.

UX a design síce musia zabezpečiť, aby boli rozličné weby celistvé po vizuálnej a funkčnej stránke, ale tak isto developeri by mali vyvíjať podľa aspoň hrubých a jasných pravidiel (napríklad v bodoch ako “nepoužívaj !important alebo inline štýly v CSS”, “naming convention v CSS a JS” a podobne), aby sme sa vyhli chaosu — a na druhej strane, rovnako podstatne, nediktovali zbytočné pravidlá, kde ich netreba.

Príklady guidelines pre F/E mimo governmentu:
https://isobar-idev.github.io/code-standards/
https://taitems.github.io/Front-End-Development-Guidelines/
http://www.yellowshoe.com.au/standards/

Domnievam sa, že úplne stačí jeden markdown súbor, ako napríklad:

3 Likes

Neexistuje na toto nejaky poloautomaticky linter?

Existuje. Otazka je ako ho nasetupovat. Uvediem stupidny a klasicky flame priklad — ma linter kontrolovat taby alebo 4 medzery vo formatovani :slight_smile:

No tam mierim, ze kolko z tohto ma nejaky realny vyznam vynucovat.

No ma realny zmysel vynucovat doslova uzitocne veci. V javascripte su to === namiesto ==, zabudbute bodkociarky, naming convencie aspon variables a podobne.

Sikana je zbytocna, ale aspon veci, ktore nevyhnutne mozu viest k errorom, ma zmysel spisat a vyhnut sa im (netreba vynucovat linterom).

Vedeli by sme spravit nejaky Checklist pre best practices + linter pre taketo veci? Idealne ako gdoc na uvod.

Ked pouzijes nejaky open source projekt, tak ten projekt moze mat vlastne best practises. Teraz sa mi skor jedna o formatovanie kodu, ako o general best practises.

Co nieco taketo? Checklists

Tak na JavaScript jednoznačne a bez okolkov by som povinne používal eslint a ako základ by som zvolil konfiguráciu od AirBnb. Jednak je to už dnes najviac používaný linter a jednak je najrozšíriteľnejší.

Navrhoval by som to spraviť tak, že vytvoríme repozitár v našej organizácii s názvom javascript, v ňom vytvoríme package.json a ako npm dependency nainštalujeme eslint-config-airbnb. Ďalej vytvoríme súbor .eslintrc (kľudne sa môže názov poupraviť ak ich budeme mať viac) a v ňom využijeme extend. V tomto súbore môžeme pozmeniť sensible defaults z predvoleného airbnb súboru s ktorými nebudeme súhlasiť.

Potom v každom FE projekte budeme využívať ten náš custom .eslintrc, ktorý sme vyššie vytvorili a to rovnakým spôsobom za použitia extend, kedže to eslint umožňuje používať aj pri viacnásobnom “rozširovaní”. Nemusíme vôbec nič publishovať na public npm, keďže npm umožňuje inštalovať deps priamo z GitHubu (ale aj GitLabu a BitBucketu).

V eslint sa dajú nastaviť 3 rôzne úrovne hlásenia - vypnuté, warning a error, pričom posledné menované spôsobuje chybový exit kód, čiže toto vieme využiť na CI serveri na zabránenie buildu kódu, ktorý nepodlieha naším coding pravidlám. Zároveň, ak dôjde k situácii, že niečo sa v novej verzii eslint sprísni a začnú nám padať buildy vieme veľmi ľahko a rýchlo dočasne vypnúť problémové pravidlo a neskôr po oprave kódu ho naspäť zapnúť práve vďaka tomu, že naše aplikácie budú mať ako dependency náš javascript coding styleguide z jeho master vetvy, takže akonáhle sa pushnu zmeny do remote repozitára na GH, prejavia sa vo všetkých projektoch (toto samozrejme vieme podľa potrieb regulovať aj vytváraním dočasných vetiev).

Snáď je to pochopiteľné. Prepáčte za totálne dumb vysvetlenie, ale keďže neviem nakoľko, kto pozná eslint, radšej som sa snažil to vysvetliť polopatisticky. Inak viem s tým pomôcť takže stačí sa dohodnúť a môžem to celé setupnúť a predviesť. Používali sme tento setup vo firme a fungovalo to veľmi dobre a spoľahlivo.

Ešte dodám, že hlavne pri projektoch, kde je vysoká pravdepodobnosť, že na ňom bude robiť veľa ľudí časom má význam enforcovať veľmi striktnú politiku na písanie kódu, ktorý potom vyzerá úplne rovnako vo všetkých aplikáciach danej organizácie a vyzerá, ako by ho písall jeden človek.

K CSS potom existuje obdobná vec - stylelint ktorá je mimoriadne podobná svojmu JS bratovi.

1 Like

A áno z vyššieho pohľadu na aplikáciu by som odporúčal mať aj checklisty, ktoré uvádza Jano.

Inak celkovo sa špecializujem na F/E a Node, takže s čímkoľvek z tohto okruhu viem určite pomôcť alebo aspoň správne nasmerovať.

Ja v podstate suhlasim s Janom s tym jednoduchym check listom, kde by sme vypisali vsetko potrebne, co by zhruba mal obsahovat a splnat kazdy front-end repozitar.

Klady takehoto riesenia:

  • Je to optional, ale moze to byt ad-hoc forcovane a odkontrolovane vsetkymi
  • Takmer nulovy barrier to entry
  • Moze byt pouzitelne a upravovane aj neprogramatormi (napr. designermi)
  • Vysvetlitelne uradnikovy v statnej sprave za 10 sekund
  • Moznost mat rovnaky sposob checkingu pre designerov / programatorov / analytikov / ux …

Zapory spomenuteho lintu (resp. podobnej alternativy):

  • Treba mat specialne repository + readme + vediet co je github + obsluhovat git
  • Treba poznat samotny eslint + vediet ho configurovat + vediet konvencie .eslintrc
  • Treba mat v kazdom projekte package.json + mat Node + npm + vediet ich obsluhovat
  • Aj zjednodusene vysvetlenie prave stalo 30 riadkov, cize sme zvysili barrier to entry

Otázka:
Čo vlastne očakávame od toho styleguide?

Protiargument:
Zo skúsenosti Ti rovno poviem, že takýto textový styleguide si nikto neprečíta, lebo je to práca navyše. A aj keď si to niekto prečíta, tak si nebude pamätať všetky pravidlá a nebude sa k tomu chcieť opakovane vracať, aby si osviežil pamäť lebo je to redundantná robota. Preto má obrovský význam tieto veci automatizovať do maximálnej možnej miery. Setupovať to aj tak bude človek, čo to vie urobiť a v prípade že sa vydáme cestou opísanou vyššie to bude také jednoduché, že postačí spustiť jediný npm príkaz a vytvoriť jednoduchý textový súbor ktorý bude mať 3 riadky (pričom aj toto by sa mohlo dať vyriešiť postinstall skriptom, ktorý by zabezpečil, že sa ten súbor vytvorí, ak ešte neexistuje). A k tomu, že je potrebný node - no a? Dnes je to už štandardný tooling.

PS: Snažím sa len diskutovať, netreba to brať ako vnucovanie vlastných názorov.

Skusim navrh, kvoli lahsej predstave, spomenuteho check listu:

  • Pouzite HTML pouziva vsade 5tkovy Doctype
  • Vsetky obrazky maju ALT parameter, pre citacky
  • CSS nepouziva !important v ziadnom subore okrem 3rd party libs
  • Vsetky JS su loadnute asynchronne a neblokuju sa
  • Inputy maju HTML5 type, kde je to mozne, podla kontextu
  • Pri kazdom regexpe je aspon nejaky komentar — heh
  • CSS rules nepouzivaju viac selectorov, nez je nevyhnutne
  • IF statementy pouzivaju === namiesto == bez vynimky
  • Kod je v produkcii minifikovany (CSS, HTML aj JS)
  • Web je responzivny, pokial nie je nevyhnutne inak
  • Snazit sa prechadzat globalnym variables v Javascripte
  • Pouzit .editorconfig v sulade s ostatnymi projektami Iniciativy
1 Like

Áno, ja súhlasím aj s týmto checklistom, lebo nie všetky veci vieš jednoducho automaticky odkontrolovať. Tamto sa vyslovene týka CSS a JS keďže v ňom vie vzniknúť poriadny neporiadok. Zopár poznámok:

  • K bodu o počte CSS selectorov - priložiť odkaz na BEM.
  • K bodu o editorconfig - opäť priložiť link na nejaký náš štandardný editorconfig - stačí jeden, keďže sa dajú konfigurovať nastavenia “per extension”

@mareksuscak ja s tebou suhlasim a na kazdom projekte, kde osobne pracujem pouzivam lint a forcujem formatting, rovnako ako best practives, ako GIT hook este pred commitovanim. Lenze tu ide o to, ze cim viac zvysime potrebny knowledge na to, aby nieco niekto vedel urobit, tym horsie.

Podla mna by bola mozno rozumna kombinacia oboch — vytvorit checklist, ktory by ludia pouzivali a snazili sa ho splnit co najviac, a napriklad sucastou neho dat jeden bod typu “dodrzat konvencie odporucane eslintom, ktory sme pre vas vytvorili a lezi v tomto a tomto repe a mozete ho takto a takto spustit”.

Typ padom by vedel dodrzovat nejake zakladne odporucania kazdy developer, aj zaciatocnik, a skilled dev by sa pozrel naozaj na ten konkretny bod, kedze vie, co robi.

1 Like

Áno, takto som to aj navrhoval vyššie - skombinovať obidva postupy. Potrebuješ tak či tak nejaký entry point, odkiaľ sa ľudia vedia dostať ku všetkým veciam týkajúcim sa styleguide - čiže možno repozitár styleguides alebo checklist alebo playbook (čokoľvek dostatočne výstižné) - v ňom mať readme, v ktorom bude priamo vyššie spomínaný checklist + k bodu o JS a CSS bude link na inštrukcie ako dostať do projektu eslint, prípadne stylelint.

Ešte dám do pozornosti playbook od Thoughtbot-u keďže obsahuje zaujímavé veci aj z tejto oblasti - https://playbook.thoughtbot.com/ - ale to je už vzdialenejšia budúcnosť.

UPDATE: Teda nemusíme enforcovať ľudí, aby eslint používali hneď od začiatku, ale pre projekty, ktoré už vyšli z fázy prototypu a plánuje sa dlhodobá údržba rôznymi developermi by to nebolo odveci mať, takže ako optional bod určite.

1 Like

Ako to chces riesit ked napr. Drupal dodava vlastny ecslint aj csslint? Bud nebudem robit podla best practises projektu, na ktorom to budem stavat alebo nebudem dodrziavat best practises s.d

Výnimky z pravidla samozrejme existujú no tu vyvstáva otázka, či mixovať príliš veľa rôznych technológii bude udržateľné z dlhodobého hľadiska. Viď napr. e-gov Veľkej Británie - prevažne sa snažia technológie príliš nemixovať z toho čo som vyčítal a používajú viac menej Ruby a Rails. A ja osobne to považujem za good practice.

wtf? e-gov riesi milion roznych veci, na ktore budem pouzivat technologie, ktore sa na vyriesenie toho problemu najlepsie hodia.