W tym artykule zbieramy do kupy rzeczy, na które powinniśmy zwracać uwagę przed oddaniem review / w trakcie robienia komuś review. Umieszczam tutaj kwestie, które pojawiły się już kilka razy, abyśmy mogli im łatwiej zapobiegać na przyszłość. Póki co lista jest niewielka, ale będzie rosła z czasem. Każdy z punktów jest nagłówkiem, do którego można bezpośrednio linkować - zachęcam Reviewersów do linkowania do konkretnych sekcji w swoich komentarzach do diffów. # 0. Komunikacja w zespole ## 0.1 Komentarze do review ### 0.1.1 Starannie wybieraj słownictwo i formy gramatyczne Zadaniem reviewera jest krytykować kod, a nie jego autora. Warto wyrażać to także przy wyborze słów i form gramatycznych w trakcie pisania komentarzy. Lepiej jest napisać "X jest źle zrobione" niż "źle zrobiłeś X". ### 0.1.2 Daj znać, gdy jakiś fragment kodu jest niezrozumiały Jeżeli nie rozumiesz jakiegoś fragmentu kodu, napisz o tym w komentarzu - możesz poprosić autora kodu o to, aby (i/lub): * zrefaktorował kod do bardziej deklaratywnej postaci (patrz zasada 1.3); * zmienił nazwy zmiennych i funkcji aby skuteczniej wyrazić swoją intencję; * opatrzył kod komentarzem; * dodał lub poszerzył dokumentację kodu; * odpowiedział na pytania recenzenta w komentarzu do diffa; # 1. Ogólne ## 1.1 Formatuj kod za pomocą Prettiera Prettier pozwala na automatyczne formatowanie wielu rodzajów plików - w tym html, js, jsx, css, scss. Jeżeli piszesz kod w języku wspieranym przez prettiera, to zadbaj o to, aby był nim sformatowany. Więcej informacji o Prettierze znajdziesz tutaj: ## 1.2 DRY - don't repeat yourself Co do zasady nie powinniśmy się powtarzać. Jeżeli jakiś fragment kodu się powtarza to warto zastanowić się, czy każdy z powtarzanych segmentów nie realizuje czasem tej samej intencji. Jeżeli tak, to rodzi to problem - jeżeli w przyszłości nasza intencja lub sposób jej realizacji się zmieni, to będziemy musieli pamiętać aby nanieść odpowiednie zmiany w każdym powtarzającym się miejscu. Aby temu zapobiec należy wyciągnąć ten kod do osobnego modułu/mixina/funkcji. ### 1.2.1 Not too DRY Czasem widzimy dwa bardzo podobne fragmenty kodu i korci nas, aby je wpiąć w jeden moduł/funkcję/selektor. Jednak jeżeli te dwa fragmenty realizują inną intencję, a ich podobieństwo jest zwykłym zbiegiem okoliczności, to lepiej nie łączyć ich w jedną jednostkę - bo gdy intencja któregoś z nich się zmieni, trzeba będzie dokonywać ponownego rozdzielenia. ## 1.3 Wyrażaj swoją intencję wprost To jest bardzo miękka zasada, ale zachęcam aby myśleć o niej często przy pisaniu kodu. Zilustruję ją prostym przykładem: ``` lang=html, name=complicated.html <style> .wrapper:before, .wrapper:after { display: inline-block; content: " "; width: 1rem; } </style> <div class="wrapper"><span class="content">Ala ma kota</span></div> ``` ``` lang=html, name=direct.html <style> .content { margin: 1rem; } </style> <div class="wrapper"><span class="content">Ala ma kota</span></div> ``` Obydwa powyższe przykłady dają taki sam efekt wizualny: napis "ala ma kota" ma oddech z prawej i lewej strony. Ale w `direct.html` kod znacznie klarowniej wyraża naszą intencję: właściwie wprost mówi nam, co chcieliśmy osiągnąć. Oczywiście czasem technologia, z której korzystamy nie pozwala nam ująć naszych intencji w bezpośredni sposób - ale jeżeli tylko mamy taką możliwość, powinniśmy zawsze sięgać po bardziej czytelne rozwiązanie. ### 1.3.1 Deklaratywny kod pomaga jaśniej wyrażać swoją intencję Kiedy wyrażamy swoją intencję w kodzie, często pierwszym narzędziem, po jakie sięgamy są pętle, wyrażenia if/else i inne podstawowe składowe języka. Tak bardzo skupiamy się na tym, *jak kod ma działać*, że osoba czytająca go może mieć problem ze zrozumieniem, *co ten kod robi*. Warto wtedy dodać warstwę abstrakcji, która uczytelni kod i ułatwi jego zmianę w przyszłości. ### 1.3.2 Unikaj if-ów z negacją Dodanie negacji do dowolnego zdania sprawia, że jego zrozumienie wymaga więcej wysiłku. "Skłamałbym gdybym powiedział, że nie wiem co to zdanie znaczy" jest trudniejsze do sparsowania, niż "Wiem co to zdanie znaczy". Podobnie ``` lang=js if( !i_can_pet_seal() ){ be_disappointed(); } else { pet_seal(); } ``` Jest mniej klarowne niż ``` lang=js if( i_can_pet_seal() ) { pet_seal(); } else { be_disappointed(); } ``` # 2. HTML (jeżeli zawierasz w HTML pełne zdania, to pamiętaj także o zasadach z sekcji "Proza" (poniżej) ## 2.1 Obrazki ### 2.1.1 Atrybut `alt` Każdy tag `img` musi zawierać atrybut `alt`. Jeżeli obrazek zawiera treść, a nie jest tylko ozdobą strony, to należy jako wartość atrybutu `alt` podać słowny opis tego obrazka - kierowany do osób nie widomych. Co widać na obrazku? Jakie treści się w nim znajdują? Jeżeli obrazek jest po prostu ozdobnym tekstem, możemy po prostu przepisać ten tekst do atrybutu `alt` Jeżeli obrazek jest tylko ozdobą/ornamentem strony, ustawiamy `alt=""`. ### 2.1.2 Responsywność Zadbaj o to, aby obrazki były responsywne - zob. https://blog.sealcode.org/post/12/responsywne_obrazki_w_html/ ## 2.2 Klikalność Elementy klikalne powinny: * mieć duży obszar, który reaguje na klikanie. Małe ikonki powinny reagować na kliknięcie nawet, gdy klikniemy trochę obok samej ikony. Linki stylowane na buttony powinny reagować na kliknięcie nie tylko na tekst, ale także na całe tło buttona (albo nawet na obszar dookoła); * zmieniać kursor na "pointer" po najechaniu na nie; * po najechaniu kursorem zmieniać swój kolor, rozmiar, lub w jakikolwiek inny sposób zapraszać do kliknięcia. ## 2.2 Nazwy klas (BEM) Nazywamy klasy zgodnie z nomenklaturą [BEM](http://getbem.com/) ### 2.2.1 Prawidłowe stosowanie podziału na Block, Element i Modifier Tworzymy nowy Block, gdy napotykamy komponent który jest semantycznie samodzielny. Element jest zawsze powiązany semantycznie z Blockiem - np. "element **paginacji**", "opcja w **menu**" Modifier jest dodawany, aby zmienić stan/wyróżnienie danego elementu. ### 2.2.2 Unikanie nadmiarowego zagnieżdżania Każdy Block jest samodzielny, nawet jeżeli akurat znajduje się wewnątrz innego Blocku. Rozpatrzmy to na przykładzie paska nawigacji, na którym widnieje zdjęcie profilowe aktualnie zalogowanego użytkownika. Zdjęcie użytkownika nie jest semantycznie powiązane z paskiem nawigacji, więc jest Blokiem - a nie Elementem wewnątrz navbara. W tym wypadku lepiej utworzyć osobne bloki "navbar" i "profile-picture", zamiast tworzyć nadmiarowo zagnieżdżoną klasę "navbar__profile-picture". ### 2.2.3 Dodawanie wszystkich potrzebnych klas Jeżeli stosujemy modifier do jakiegoś elementu, w jego tagu `class` powinny znaleźć się zarówno klasa bazowa, jak i ta opatrzona modyfikatorem: ``` lang=html <div class="navbar__item"></div> <div class="navbar__item navbar__item--selected"></div> ``` ## 2.3 Layout ### 2.3.1 Tekst ma jak oddychać Tekst prezentuje się najlepiej, gdy ma oddech - czyli nie przykleja się do krawędzi ekranu/swojego kontenera. Warto zwrócić na to uwagę w szczególności przy projektach, które powinny być responsywne. Sprawdź, czy dla którejś szerokości ekranu nie dzieje się coś takiego: {F45497} Czasem dodanie zwykłego paddingu lub marginesu w odpowiednim miejscu rozwiązuje problem. Pamiętaj przy tym o [wyrażaniu swoich intencji wprost](https://hub.sealcode.org/w/sealhub_workflow/standardy/#1-3-wyra-aj-swoj-intencj). ## 2.4 Obfuskacja Aby utrudnić życie spam-botom, warto poddać obfuskacji adresy email umieszczone w publicznie dostępnych dokumentach html. Jedną ze skuteczniejszych metod obfuskacji jest [zamiana każdej litery adresu na jej html-owy odpowiednik](https://stackoverflow.com/a/748804/1467284) # 3 Proza ## 3.1 Unikaj wiszących spójników Zadbaj, aby tekst był złożony tak, aby nie zawierał [wiszących spójników](https://pl.wikipedia.org/wiki/Sierotka_(typografia)). Możesz to osiągnąć za pomocą twardych spacji (HTML: `&nbsp;`) lub odpowiedniej konfiguracji programu do składu tekstu. ## 3.2 Używaj prawidłowych znaków typograficznych ### 3.2.1 Apostrof Znak `'`, o ile powszechnie używany w roli apostrofu, nie jest apostrofem. Prawidłowym znakiem typograficznym reprezentującym apostrof jest znak `RIGHT SINGLE QUOTATION MARK` (HEX: 2019, DEC: 8217; zob. http://unicode.org/Public/UNIDATA/NamesList.txt), który wyglada tak: ’ Uwaga na znacznik `&apos;` w html, gdyż odpowiada on znakowi `'`, a nie apostrofowi. Prawidłowym znacznikiem apostrofu w html jest `&rsquo;` (można go też zapisać jako &#8217;) ### 3.2.2 Ampersand Znak `&` ma szczególne znaczenie, bo służy do tworzenia encji jak np. `&nbsp;`. Chcąc wyświetlić ampersand na stronie należy użyć znacznika `&amp;` # UI ## Asynchroniczne operacje (czekanie) Nikt nie lubi czekać. Gdy program wykonuje jakąś czasochłonną operację to załóż, w niektórych sytuacjach może ona trwać 10, a nawet 100 razy dłużej. Może to być spowodowane trudnymi warunkami sieciowymi, starszym sprzętem lub ponadprzeciętnie dużą ilością danych do przetworzenia. Jeżeli to możliwe, wyświetl w interfejsie: * informację o aktualnym stadium procesu (np. progress bar, ew. spinner) * informację o przewidywanym czasie zakończenia W wypadku błędu: * wyświetl informację o niepowodzeniu. Postaraj się, aby była czytelna i żeby użytkownik mógł stwierdzić, co jest przyczyną błędu * jeżeli operacja zawiodła z przyczyn niezależnych od użytkownika, automatycznie spróbuj ponowić operację (jeżeli to możliwe i stosowne w danej sytuacji)

W tym artykule zbieramy do kupy rzeczy, na które powinniśmy zwracać uwagę przed oddaniem review / w trakcie robienia komuś review. Umieszczam tutaj kwestie, które pojawiły się już kilka razy, abyśmy mogli im łatwiej zapobiegać na przyszłość. Póki co lista jest niewielka, ale będzie rosła z czasem. Każdy z punktów jest nagłówkiem, do którego można bezpośrednio linkować - zachęcam Reviewersów do linkowania do konkretnych sekcji w swoich komentarzach do diffów. # 0. Komunikacja w zespole ## 0.1 Komentarze do review ### 0.1.1 Starannie wybieraj słownictwo i formy gramatyczne Zadaniem reviewera jest krytykować kod, a nie jego autora. Warto wyrażać to także przy wyborze słów i form gramatycznych w trakcie pisania komentarzy. Lepiej jest napisać "X jest źle zrobione" niż "źle zrobiłeś X". ### 0.1.2 Daj znać, gdy jakiś fragment kodu jest niezrozumiały Jeżeli nie rozumiesz jakiegoś fragmentu kodu, napisz o tym w komentarzu - możesz poprosić autora kodu o to, aby (i/lub): * zrefaktorował kod do bardziej deklaratywnej postaci (patrz zasada 1.3); * zmienił nazwy zmiennych i funkcji aby skuteczniej wyrazić swoją intencję; * opatrzył kod komentarzem; * dodał lub poszerzył dokumentację kodu; * odpowiedział na pytania recenzenta w komentarzu do diffa; # 1. Ogólne ## 1.1 Formatuj kod za pomocą Prettiera Prettier pozwala na automatyczne formatowanie wielu rodzajów plików - w tym html, js, jsx, css, scss. Jeżeli piszesz kod w języku wspieranym przez prettiera, to zadbaj o to, aby był nim sformatowany. Więcej informacji o Prettierze znajdziesz tutaj: ## 1.2 DRY - don't repeat yourself Co do zasady nie powinniśmy się powtarzać. Jeżeli jakiś fragment kodu się powtarza to warto zastanowić się, czy każdy z powtarzanych segmentów nie realizuje czasem tej samej intencji. Jeżeli tak, to rodzi to problem - jeżeli w przyszłości nasza intencja lub sposób jej realizacji się zmieni, to będziemy musieli pamiętać aby nanieść odpowiednie zmiany w każdym powtarzającym się miejscu. Aby temu zapobiec należy wyciągnąć ten kod do osobnego modułu/mixina/funkcji. ### 1.2.1 Not too DRY Czasem widzimy dwa bardzo podobne fragmenty kodu i korci nas, aby je wpiąć w jeden moduł/funkcję/selektor. Jednak jeżeli te dwa fragmenty realizują inną intencję, a ich podobieństwo jest zwykłym zbiegiem okoliczności, to lepiej nie łączyć ich w jedną jednostkę - bo gdy intencja któregoś z nich się zmieni, trzeba będzie dokonywać ponownego rozdzielenia. ## 1.3 Wyrażaj swoją intencję wprost To jest bardzo miękka zasada, ale zachęcam aby myśleć o niej często przy pisaniu kodu. Zilustruję ją prostym przykładem: ``` lang=html, name=complicated.html <style> .wrapper:before, .wrapper:after { display: inline-block; content: " "; width: 1rem; } </style> <div class="wrapper"><span class="content">Ala ma kota</span></div> ``` ``` lang=html, name=direct.html <style> .content { margin: 1rem; } </style> <div class="wrapper"><span class="content">Ala ma kota</span></div> ``` Obydwa powyższe przykłady dają taki sam efekt wizualny: napis "ala ma kota" ma oddech z prawej i lewej strony. Ale w `direct.html` kod znacznie klarowniej wyraża naszą intencję: właściwie wprost mówi nam, co chcieliśmy osiągnąć. Oczywiście czasem technologia, z której korzystamy nie pozwala nam ująć naszych intencji w bezpośredni sposób - ale jeżeli tylko mamy taką możliwość, powinniśmy zawsze sięgać po bardziej czytelne rozwiązanie. ### 1.3.1 Deklaratywny kod pomaga jaśniej wyrażać swoją intencję Kiedy wyrażamy swoją intencję w kodzie, często pierwszym narzędziem, po jakie sięgamy są pętle, wyrażenia if/else i inne podstawowe składowe języka. Tak bardzo skupiamy się na tym, *jak kod ma działać*, że osoba czytająca go może mieć problem ze zrozumieniem, *co ten kod robi*. Warto wtedy dodać warstwę abstrakcji, która uczytelni kod i ułatwi jego zmianę w przyszłości. ### 1.3.2 Unikaj if-ów z negacją Dodanie negacji do dowolnego zdania sprawia, że jego zrozumienie wymaga więcej wysiłku. "Skłamałbym gdybym powiedział, że nie wiem co to zdanie znaczy" jest trudniejsze do sparsowania, niż "Wiem co to zdanie znaczy". Podobnie ``` lang=js if( !i_can_pet_seal() ){ be_disappointed(); } else { pet_seal(); } ``` Jest mniej klarowne niż ``` lang=js if( i_can_pet_seal() ) { pet_seal(); } else { be_disappointed(); } ``` # 2. HTML (jeżeli zawierasz w HTML pełne zdania, to pamiętaj także o zasadach z sekcji "Proza" (poniżej) ## 2.1 Obrazki ### 2.1.1 Atrybut `alt` Każdy tag `img` musi zawierać atrybut `alt`. Jeżeli obrazek zawiera treść, a nie jest tylko ozdobą strony, to należy jako wartość atrybutu `alt` podać słowny opis tego obrazka - kierowany do osób nie widomych. Co widać na obrazku? Jakie treści się w nim znajdują? Jeżeli obrazek jest po prostu ozdobnym tekstem, możemy po prostu przepisać ten tekst do atrybutu `alt` Jeżeli obrazek jest tylko ozdobą/ornamentem strony, ustawiamy `alt=""`. ### 2.1.2 Responsywność Zadbaj o to, aby obrazki były responsywne - zob. https://blog.sealcode.org/post/12/responsywne_obrazki_w_html/ ## 2.2 Klikalność Elementy klikalne powinny: * mieć duży obszar, który reaguje na klikanie. Małe ikonki powinny reagować na kliknięcie nawet, gdy klikniemy trochę obok samej ikony. Linki stylowane na buttony powinny reagować na kliknięcie nie tylko na tekst, ale także na całe tło buttona (albo nawet na obszar dookoła); * zmieniać kursor na "pointer" po najechaniu na nie; * po najechaniu kursorem zmieniać swój kolor, rozmiar, lub w jakikolwiek inny sposób zapraszać do kliknięcia. ## 2.2 Nazwy klas (BEM) Nazywamy klasy zgodnie z nomenklaturą [BEM](http://getbem.com/) ### 2.2.1 Prawidłowe stosowanie podziału na Block, Element i Modifier Tworzymy nowy Block, gdy napotykamy komponent który jest semantycznie samodzielny. Element jest zawsze powiązany semantycznie z Blockiem - np. "element **paginacji**", "opcja w **menu**" Modifier jest dodawany, aby zmienić stan/wyróżnienie danego elementu. ### 2.2.2 Unikanie nadmiarowego zagnieżdżania Każdy Block jest samodzielny, nawet jeżeli akurat znajduje się wewnątrz innego Blocku. Rozpatrzmy to na przykładzie paska nawigacji, na którym widnieje zdjęcie profilowe aktualnie zalogowanego użytkownika. Zdjęcie użytkownika nie jest semantycznie powiązane z paskiem nawigacji, więc jest Blokiem - a nie Elementem wewnątrz navbara. W tym wypadku lepiej utworzyć osobne bloki "navbar" i "profile-picture", zamiast tworzyć nadmiarowo zagnieżdżoną klasę "navbar__profile-picture". ### 2.2.3 Dodawanie wszystkich potrzebnych klas Jeżeli stosujemy modifier do jakiegoś elementu, w jego tagu `class` powinny znaleźć się zarówno klasa bazowa, jak i ta opatrzona modyfikatorem: ``` lang=html <div class="navbar__item"></div> <div class="navbar__item navbar__item--selected"></div> ``` ## 2.3 Layout ### 2.3.1 Tekst ma jak oddychać Tekst prezentuje się najlepiej, gdy ma oddech - czyli nie przykleja się do krawędzi ekranu/swojego kontenera. Warto zwrócić na to uwagę w szczególności przy projektach, które powinny być responsywne. Sprawdź, czy dla którejś szerokości ekranu nie dzieje się coś takiego: {F45497} Czasem dodanie zwykłego paddingu lub marginesu w odpowiednim miejscu rozwiązuje problem. Pamiętaj przy tym o [wyrażaniu swoich intencji wprost](https://hub.sealcode.org/w/sealhub_workflow/standardy/#1-3-wyra-aj-swoj-intencj). ## 2.4 Obfuskacja Aby utrudnić życie spam-botom, warto poddać obfuskacji adresy email umieszczone w publicznie dostępnych dokumentach html. Jedną ze skuteczniejszych metod obfuskacji jest [zamiana każdej litery adresu na jej html-owy odpowiednik](https://stackoverflow.com/a/748804/1467284) # 3 Proza ## 3.1 Unikaj wiszących spójników Zadbaj, aby tekst był złożony tak, aby nie zawierał [wiszących spójników](https://pl.wikipedia.org/wiki/Sierotka_(typografia)). Możesz to osiągnąć za pomocą twardych spacji (HTML: `&nbsp;`) lub odpowiedniej konfiguracji programu do składu tekstu. ## 3.2 Używaj prawidłowych znaków typograficznych ### 3.2.1 Apostrof Znak `'`, o ile powszechnie używany w roli apostrofu, nie jest apostrofem. Prawidłowym znakiem typograficznym reprezentującym apostrof jest znak `RIGHT SINGLE QUOTATION MARK` (HEX: 2019, DEC: 8217; zob. http://unicode.org/Public/UNIDATA/NamesList.txt), który wyglada tak: ’ Uwaga na znacznik `&apos;` w html, gdyż odpowiada on znakowi `'`, a nie apostrofowi. Prawidłowym znacznikiem apostrofu w html jest `&rsquo;` (można go też zapisać jako &#8217;) ### 3.2.2 Ampersand Znak `&` ma szczególne znaczenie, bo służy do tworzenia encji jak np. `&nbsp;`. Chcąc wyświetlić ampersand na stronie należy użyć znacznika `&amp;` # 4. UI ## 4.1 Asynchroniczne operacje (czekanie) Nikt nie lubi czekać. Gdy program wykonuje jakąś czasochłonną operację to załóż, w niektórych sytuacjach może ona trwać 10, a nawet 100 razy dłużej. Może to być spowodowane trudnymi warunkami sieciowymi, starszym sprzętem lub ponadprzeciętnie dużą ilością danych do przetworzenia. Jeżeli to możliwe, wyświetl w interfejsie: * informację o aktualnym stadium procesu (np. progress bar, ew. spinner) * informację o przewidywanym czasie zakończenia W wypadku błędu: * wyświetl informację o niepowodzeniu. Postaraj się, aby była czytelna i żeby użytkownik mógł stwierdzić, co jest przyczyną błędu * jeżeli operacja zawiodła z przyczyn niezależnych od użytkownika, automatycznie spróbuj ponowić operację (jeżeli to możliwe i stosowne w danej sytuacji)

W tym artykule zbieramy do kupy rzeczy, na które powinniśmy zwracać uwagę przed oddaniem review / w trakcie robienia komuś review. Umieszczam tutaj kwestie, które pojawiły się już kilka razy, abyśmy mogli im łatwiej zapobiegać na przyszłość. Póki co lista jest niewielka, ale będzie rosła z czasem. Każdy z punktów jest nagłówkiem, do którego można bezpośrednio linkować - zachęcam Reviewersów do linkowania do konkretnych sekcji w swoich komentarzach do diffów. # 0. Komunikacja w zespole ## 0.1 Komentarze do review ### 0.1.1 Starannie wybieraj słownictwo i formy gramatyczne Zadaniem reviewera jest krytykować kod, a nie jego autora. Warto wyrażać to także przy wyborze słów i form gramatycznych w trakcie pisania komentarzy. Lepiej jest napisać "X jest źle zrobione" niż "źle zrobiłeś X". ### 0.1.2 Daj znać, gdy jakiś fragment kodu jest niezrozumiały Jeżeli nie rozumiesz jakiegoś fragmentu kodu, napisz o tym w komentarzu - możesz poprosić autora kodu o to, aby (i/lub): * zrefaktorował kod do bardziej deklaratywnej postaci (patrz zasada 1.3); * zmienił nazwy zmiennych i funkcji aby skuteczniej wyrazić swoją intencję; * opatrzył kod komentarzem; * dodał lub poszerzył dokumentację kodu; * odpowiedział na pytania recenzenta w komentarzu do diffa; # 1. Ogólne ## 1.1 Formatuj kod za pomocą Prettiera Prettier pozwala na automatyczne formatowanie wielu rodzajów plików - w tym html, js, jsx, css, scss. Jeżeli piszesz kod w języku wspieranym przez prettiera, to zadbaj o to, aby był nim sformatowany. Więcej informacji o Prettierze znajdziesz tutaj: ## 1.2 DRY - don't repeat yourself Co do zasady nie powinniśmy się powtarzać. Jeżeli jakiś fragment kodu się powtarza to warto zastanowić się, czy każdy z powtarzanych segmentów nie realizuje czasem tej samej intencji. Jeżeli tak, to rodzi to problem - jeżeli w przyszłości nasza intencja lub sposób jej realizacji się zmieni, to będziemy musieli pamiętać aby nanieść odpowiednie zmiany w każdym powtarzającym się miejscu. Aby temu zapobiec należy wyciągnąć ten kod do osobnego modułu/mixina/funkcji. ### 1.2.1 Not too DRY Czasem widzimy dwa bardzo podobne fragmenty kodu i korci nas, aby je wpiąć w jeden moduł/funkcję/selektor. Jednak jeżeli te dwa fragmenty realizują inną intencję, a ich podobieństwo jest zwykłym zbiegiem okoliczności, to lepiej nie łączyć ich w jedną jednostkę - bo gdy intencja któregoś z nich się zmieni, trzeba będzie dokonywać ponownego rozdzielenia. ## 1.3 Wyrażaj swoją intencję wprost To jest bardzo miękka zasada, ale zachęcam aby myśleć o niej często przy pisaniu kodu. Zilustruję ją prostym przykładem: ``` lang=html, name=complicated.html <style> .wrapper:before, .wrapper:after { display: inline-block; content: " "; width: 1rem; } </style> <div class="wrapper"><span class="content">Ala ma kota</span></div> ``` ``` lang=html, name=direct.html <style> .content { margin: 1rem; } </style> <div class="wrapper"><span class="content">Ala ma kota</span></div> ``` Obydwa powyższe przykłady dają taki sam efekt wizualny: napis "ala ma kota" ma oddech z prawej i lewej strony. Ale w `direct.html` kod znacznie klarowniej wyraża naszą intencję: właściwie wprost mówi nam, co chcieliśmy osiągnąć. Oczywiście czasem technologia, z której korzystamy nie pozwala nam ująć naszych intencji w bezpośredni sposób - ale jeżeli tylko mamy taką możliwość, powinniśmy zawsze sięgać po bardziej czytelne rozwiązanie. ### 1.3.1 Deklaratywny kod pomaga jaśniej wyrażać swoją intencję Kiedy wyrażamy swoją intencję w kodzie, często pierwszym narzędziem, po jakie sięgamy są pętle, wyrażenia if/else i inne podstawowe składowe języka. Tak bardzo skupiamy się na tym, *jak kod ma działać*, że osoba czytająca go może mieć problem ze zrozumieniem, *co ten kod robi*. Warto wtedy dodać warstwę abstrakcji, która uczytelni kod i ułatwi jego zmianę w przyszłości. ### 1.3.2 Unikaj if-ów z negacją Dodanie negacji do dowolnego zdania sprawia, że jego zrozumienie wymaga więcej wysiłku. "Skłamałbym gdybym powiedział, że nie wiem co to zdanie znaczy" jest trudniejsze do sparsowania, niż "Wiem co to zdanie znaczy". Podobnie ``` lang=js if( !i_can_pet_seal() ){ be_disappointed(); } else { pet_seal(); } ``` Jest mniej klarowne niż ``` lang=js if( i_can_pet_seal() ) { pet_seal(); } else { be_disappointed(); } ``` # 2. HTML (jeżeli zawierasz w HTML pełne zdania, to pamiętaj także o zasadach z sekcji "Proza" (poniżej) ## 2.1 Obrazki ### 2.1.1 Atrybut `alt` Każdy tag `img` musi zawierać atrybut `alt`. Jeżeli obrazek zawiera treść, a nie jest tylko ozdobą strony, to należy jako wartość atrybutu `alt` podać słowny opis tego obrazka - kierowany do osób nie widomych. Co widać na obrazku? Jakie treści się w nim znajdują? Jeżeli obrazek jest po prostu ozdobnym tekstem, możemy po prostu przepisać ten tekst do atrybutu `alt` Jeżeli obrazek jest tylko ozdobą/ornamentem strony, ustawiamy `alt=""`. ### 2.1.2 Responsywność Zadbaj o to, aby obrazki były responsywne - zob. https://blog.sealcode.org/post/12/responsywne_obrazki_w_html/ ## 2.2 Klikalność Elementy klikalne powinny: * mieć duży obszar, który reaguje na klikanie. Małe ikonki powinny reagować na kliknięcie nawet, gdy klikniemy trochę obok samej ikony. Linki stylowane na buttony powinny reagować na kliknięcie nie tylko na tekst, ale także na całe tło buttona (albo nawet na obszar dookoła); * zmieniać kursor na "pointer" po najechaniu na nie; * po najechaniu kursorem zmieniać swój kolor, rozmiar, lub w jakikolwiek inny sposób zapraszać do kliknięcia. ## 2.2 Nazwy klas (BEM) Nazywamy klasy zgodnie z nomenklaturą [BEM](http://getbem.com/) ### 2.2.1 Prawidłowe stosowanie podziału na Block, Element i Modifier Tworzymy nowy Block, gdy napotykamy komponent który jest semantycznie samodzielny. Element jest zawsze powiązany semantycznie z Blockiem - np. "element **paginacji**", "opcja w **menu**" Modifier jest dodawany, aby zmienić stan/wyróżnienie danego elementu. ### 2.2.2 Unikanie nadmiarowego zagnieżdżania Każdy Block jest samodzielny, nawet jeżeli akurat znajduje się wewnątrz innego Blocku. Rozpatrzmy to na przykładzie paska nawigacji, na którym widnieje zdjęcie profilowe aktualnie zalogowanego użytkownika. Zdjęcie użytkownika nie jest semantycznie powiązane z paskiem nawigacji, więc jest Blokiem - a nie Elementem wewnątrz navbara. W tym wypadku lepiej utworzyć osobne bloki "navbar" i "profile-picture", zamiast tworzyć nadmiarowo zagnieżdżoną klasę "navbar__profile-picture". ### 2.2.3 Dodawanie wszystkich potrzebnych klas Jeżeli stosujemy modifier do jakiegoś elementu, w jego tagu `class` powinny znaleźć się zarówno klasa bazowa, jak i ta opatrzona modyfikatorem: ``` lang=html <div class="navbar__item"></div> <div class="navbar__item navbar__item--selected"></div> ``` ## 2.3 Layout ### 2.3.1 Tekst ma jak oddychać Tekst prezentuje się najlepiej, gdy ma oddech - czyli nie przykleja się do krawędzi ekranu/swojego kontenera. Warto zwrócić na to uwagę w szczególności przy projektach, które powinny być responsywne. Sprawdź, czy dla którejś szerokości ekranu nie dzieje się coś takiego: {F45497} Czasem dodanie zwykłego paddingu lub marginesu w odpowiednim miejscu rozwiązuje problem. Pamiętaj przy tym o [wyrażaniu swoich intencji wprost](https://hub.sealcode.org/w/sealhub_workflow/standardy/#1-3-wyra-aj-swoj-intencj). ## 2.4 Obfuskacja Aby utrudnić życie spam-botom, warto poddać obfuskacji adresy email umieszczone w publicznie dostępnych dokumentach html. Jedną ze skuteczniejszych metod obfuskacji jest [zamiana każdej litery adresu na jej html-owy odpowiednik](https://stackoverflow.com/a/748804/1467284) # 3 Proza ## 3.1 Unikaj wiszących spójników Zadbaj, aby tekst był złożony tak, aby nie zawierał [wiszących spójników](https://pl.wikipedia.org/wiki/Sierotka_(typografia)). Możesz to osiągnąć za pomocą twardych spacji (HTML: `&nbsp;`) lub odpowiedniej konfiguracji programu do składu tekstu. ## 3.2 Używaj prawidłowych znaków typograficznych ### 3.2.1 Apostrof Znak `'`, o ile powszechnie używany w roli apostrofu, nie jest apostrofem. Prawidłowym znakiem typograficznym reprezentującym apostrof jest znak `RIGHT SINGLE QUOTATION MARK` (HEX: 2019, DEC: 8217; zob. http://unicode.org/Public/UNIDATA/NamesList.txt), który wyglada tak: ’ Uwaga na znacznik `&apos;` w html, gdyż odpowiada on znakowi `'`, a nie apostrofowi. Prawidłowym znacznikiem apostrofu w html jest `&rsquo;` (można go też zapisać jako &#8217;) ### 3.2.2 Ampersand Znak `&` ma szczególne znaczenie, bo służy do tworzenia encji jak np. `&nbsp;`. Chcąc wyświetlić ampersand na stronie należy użyć znacznika `&amp;` # 4. UI ## 4.1 Asynchroniczne operacje (czekanie) Nikt nie lubi czekać. Gdy program wykonuje jakąś czasochłonną operację to załóż, w niektórych sytuacjach może ona trwać 10, a nawet 100 razy dłużej. Może to być spowodowane trudnymi warunkami sieciowymi, starszym sprzętem lub ponadprzeciętnie dużą ilością danych do przetworzenia. Jeżeli to możliwe, wyświetl w interfejsie: * informację o aktualnym stadium procesu (np. progress bar, ew. spinner) * informację o przewidywanym czasie zakończenia W wypadku błędu: * wyświetl informację o niepowodzeniu. Postaraj się, aby była czytelna i żeby użytkownik mógł stwierdzić, co jest przyczyną błędu * jeżeli operacja zawiodła z przyczyn niezależnych od użytkownika, automatycznie spróbuj ponowić operację (jeżeli to możliwe i stosowne w danej sytuacji)