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. # 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. # 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.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.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). ## Proza ### 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.

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. # 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. # 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.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). ## Proza ### 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.

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. # 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. # 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 a1 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.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). ## Proza ### 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.