⚡ Document History

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.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: ```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: ` `) 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 `'` w html, gdyż odpowiada on znakowi `'`, a nie apostrofowi. Prawidłowym znacznikiem apostrofu w html jest `’` (można go też zapisać jako ’) #### 3.2.2 Ampersand Znak `&` ma szczególne znaczenie, bo służy do tworzenia encji jak np. ` `. Chcąc wyświetlić ampersand na stronie należy użyć znacznika `&`

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 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ś". # 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.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: ```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: ` `) 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 `'` w html, gdyż odpowiada on znakowi `'`, a nie apostrofowi. Prawidłowym znacznikiem apostrofu w html jest `’` (można go też zapisać jako ’) #### 3.2.2 Ampersand Znak `&` ma szczególne znaczenie, bo służy do tworzenia encji jak np. ` `. Chcąc wyświetlić ampersand na stronie należy użyć znacznika `&`

Version 16 vs 17

Edits

Content Changes