Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
README.md

README.md

Zasady tworzenia spójnych, zgodnych z regułami języka deklaracji CSS

Poniżej opisane zostały podstawowe zasady tworzenia arkuszy stylów. Nie jest to uniwersalne czy wyczerpujące temat zestawienie. Intencją autora nie było bowiem narzucanie jedynie słusznych rozwiązań, a raczej zachęta do stosowania istniejących, wypróbowanych i uznanych wzorców.

Z tego samego powodu mile widziana będzie wszelka pomoc w dalszym rozwijaniu i wzbogacaniu niniejszego dokumentu.

Artykuł Idiomatic CSS w oryginale

Spis treści

  1. Główne zasady
  2. Wcięcia
  3. Komentarze
  4. Format
  5. Nazewnictwo
  6. Przykłady praktyczne
  7. Organizacja
  8. Przygotowanie i wdrożenie

Podziękowania

1. Główne zasady

„Pierwszym krokiem do stworzenia projektu, który odniesie sukces, jest zrozumienie, że pisanie kodu dla samego siebie to Bardzo Zły Pomysł®. Jeśli z twoich rozwiązań mają korzystać tysiące innych osób, nie pisz tak, jak lubisz, ale tak, by osiągnąć maksymalną przejrzystość.” - Idan Gazit

  • Nie jesteś maszyną do kompilowania czy kompresowania kodu i nie staraj się nią zostać.
  • Kod powinien zawsze wyglądać tak, jakby napisał go jeden człowiek - niezależnie od liczby osób współpracujących przy tym zadaniu.
  • Trzymaj się ściśle ustalonych na wstępie reguł.
  • Jeśli masz wątpliwości, korzystaj z istniejących, sprawdzonych rozwiązań.

2. Wcięcia

W całym projekcie stosuj konsekwentnie tylko jeden styl wcięć. Nie zapominaj, że wcięcia służą przede wszystkim czytelności kodu.

  • Nigdy nie stosuj równolegle spacji i tabulatorów.
  • Wybierz jedną z powyższych metod do tworzenia wcięć (najlepiej spacje) i trzymaj się jej.
  • Jeśli używasz spacji, wybierz stałą liczbę znaków dla jednego poziomu wcięcia (najlepiej cztery).

Wskazówka: włącz w swoim edytorze kodu opcję pokazywania znaków niedrukowalnych. To pozwoli ci wyeliminować spacje na końcu linii i w pustych wierszach.

Wskazówka: używaj pliku EditorConfig albo innego rozwiązania, które pomoże ci trzymać się ustalonych zasad tworzenia wcięć.

3. Komentarze

Dokładne dokumentowanie kodu jest niezwykle istotne. Poświęć czas na opisanie komponentów, ich działania i ograniczeń oraz sposobu ich tworzenia. Nie pozwól, żeby inni członkowie zespołu musieli domyślać się znaczenia kodu.

Styl tworzenia komentarzy powinien być prosty i spójny w obrębie całego projektu.

  • Umieszczaj komentarze w nowej linii, nad elementem, który opisują.
  • Unikaj tworzenia komentarzy na końcu linii.
  • Utrzymuj sensowne maksimum długości linii, np. 80 znaków.
  • Używaj komentarzy do dzielenia kodu CSS na osobne sekcje.
  • Komentuj, używając standardowych zdań i wcięć akapitów.

Wskazówka: skonfiguruj swój edytor tak, byś mógł stosować skróty klawiszowe do wstawiania komentarzy w ustalonej wcześniej postaci.

Przykład:

/* ==========================================================================
   Blok komentarzy sekcji
   ========================================================================== */

/* Blok komentarzy podsekcji
   ========================================================================== */

/**
 * Krótki opis z zastosowaniem formatowania w stylu Doxygen
 *
 * Długi opis - pierwsze zdanie rozpoczyna się tutaj i biegnie jeszcze przez
 * chwilę, zajmując cały wiersz, aby wreszcie zakończyć się konkluzją w tym
 * miejscu, u dołu akapitu.
 *
 * Dłuższy opis jest najlepszym miejscem do umieszczenia szczegółowych
 * objaśnień i dokumentacji. Może zawierać przykładowy kod HTML, adresy
 * internetowe oraz inne przydatne informacje.
 *
 * @tag To jest znacznik o nazwie 'tag'
 *
 * @todo To jest opis todo, wskazujący istotne zadanie, które należy wykonać
 *   później. Zawija się po około 80 znakach a kolejne linie są wcięte za
 *   pomocą 2 spacji.
 */

/* Podstawowy komentarz */

4. Format

Wybrany format kodu musi gwarantować, że kod ten będzie łatwy do przeczytania i skomentowania, co w efekcie zminimalizuje szanse przypadkowego popełnienia błędu. W ten sposób także tworzenie przejrzystych zestawień zmian w plikach i wskazywanie osób odpowiedzialnych za określone poprawki stanie się znacznie łatwiejszym zadaniem.

  • W deklaracjach z wieloma selektorami używaj jednego selektora w linii.
  • Wstawiaj jedną spację przed nawiasem otwierającym zestaw reguł.
  • W bloku reguł umieszczaj jedną deklarację w wierszu.
  • Stosuj jeden poziom wcięcia dla każdej deklaracji.
  • Wstawiaj jedną spację po dwukropku w deklaracji.
  • Używaj wartości pisanych małymi literami i skrótów, np. #aaa.
  • Stosuj pojedyncze i podwójne cudzysłowy w sposób spójny. Preferuj jednak podwójne, jak na przykład content: "".
  • Wyodrędbniaj cudzysłowami wartości atrybutów w selektorach, na przykład input[type="checkbox"].
  • Tam gdzie to możliwe unikaj podawania jednostek dla wartości zerowych, na przykład margin: 0.
  • W oddzielonych przecinkami właściwościach wstawiaj spację po każdym przecinku.
  • Pamiętaj o średniku na końcu ostatniej deklaracji w bloku.
  • Nawias zamykający zestaw reguł umieszczaj w tej samej kolumnie (z tym samym wcięciem), co otwierający.
  • Bloki deklaracji oddzielaj pustą linią.
.selektor-1,
.selektor-2,
.selektor-3[type="text"] {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    display: block;
    font-family: helvetica, arial, sans-serif;
    color: #333;
    background: #fff;
    background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));
}

Kolejność deklaracji

Deklaracje powinny być uporządkowane zgodnie z jedną, przyjętą na wstępie regułą. Preferowanym przeze mnie sposobem jest umieszczanie na początku właściwości określających strukturę elementu - czyli np. jego pozycję i wymiary.

.selektor {
    /* Pozycja */
    position: absolute;
    z-index: 10;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;

    /* Wyświetlanie i wymiary */
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    width: 100px;
    height: 100px;
    padding: 10px;
    border: 10px solid #333;
    margin: 10px;

    /* Inne */
    background: #000;
    color: #fff
    font-family: sans-serif;
    font-size: 16px;
    text-align: right;
}

Stosunkowo popularne jest także porządkowanie deklaracji alfabetycznie. Metoda ta ma jednak taką wadę, że oddziela od siebie powiązane właściwości. W takim wypadku np. definicje marginesów, odstępów, wysokości i szerokości elementu będą rozrzucone po całym bloku.

Wyjątki i drobne odstępstwa

Duże fragmenty arkusza zawierające pojedyncze deklaracje można formatować nieco inaczej, ujmując całość w jednym wierszu. W takim wypadku po nawiasie otwierającym oraz przed zamykającym należy wstawić spację.

.selektor-1 { width: 10%; }
.selektor-2 { width: 20%; }
.selektor-3 { width: 30%; }

Dłuższe, oddzielone przecinkami właściwości, np. zestawy gradientów albo cieni, można rozbijać na kilka linii, by poprawić czytelność i ułatwić generowanie przejrzystych zestawień zmian. Poniższy przykład obrazuje jedno z możliwych rozwiązań:

.selektor {
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
}

Preprocesory: dodatkowe uwagi dotyczące formatu

Różne narzędzia do wstępnego przetwarzania kodu CSS mają zróżnicowane możliwości i składnię. W związku z tym zasady postępowania należy ustalać zawsze w odniesieniu do unikalnych właściwości danego preprocesora. Te wskazane niżej odnoszą się do jednego z nich - Sass.

  • Ogranicz zagnieżdżanie do jednego poziomu. To pozwoli ci uniknąć tworzenia nazbyt szczegółowych selektorów.
  • Unikaj stosowania dużej liczby zagnieżdżonych reguł. 20 wierszy wydaje się być rozsądną granicą. Podziel kod na mniejsze fragmenty, gdy tylko zauważysz, że traci na czytelności.
  • Pamiętaj o umieszczaniu @extend w pierwszych liniach bloku deklaracji.
  • Gdy to możliwe, grupuj @include na początku bloku deklaracji, zaraz za @extend.
  • Nazwy tworzonych przez siebie funkcji poprzedzaj x- lub innym prefiksem. Pomoże ci to odróżnić je w trakcie pracy od domyślnych funkcji CSS i uniknąć konfliktów z funkcjami zawartymi w innych bibliotekach.
.selektor-1 {
    @extend .inna-regula;
    @include clearfix();
    @include box-sizing(border-box);
    width: x-jednostka-siatki(1);
    // pozostałe deklaracje
}

5. Nazewnictwo

Wybór odpowiedniego nazewnictwa jest trudny, ale bardzo istotny. To kluczowy element w procesie tworzenia łatwej w aktualizacji i elastycznej bazy kodu CSS.

  • Unikaj zbyt częstego wykorzystywania skróconych nazw klas. Nie komplikuj kodu ponad potrzebę.
  • Używaj jasnych, kojarzących się, dobrze przemyślanych nazw klas.
  • Wybierz zrozumiały i spójny wzorzec tworzenia nazw, który będzie zrozumiały zarówno w trakcie lektury kodu HTML, jak i CSS.
  • Selektory dla komponentów strony powinny wykorzystywać nazwy klas - unikaj używania nazw tagów i identyfikatorów (id).
/* Przykład kodu z kiepskimi nazwami klas */

.m-prz {
    overflow: auto;
}

.tk {
    background: #000;
}

/* Przykład kodu z lepszymi nazwami */

.mozna-przewijac {
    overflow: auto;
}

.tekst-kolumny {
    background: #000;
}

6. Przykłady praktyczne

Propozycje zastosowania opisanych wcześniej konwencji.

/* ==========================================================================
   Siatka
   ========================================================================== */

/**
 * Przykładowy kod HTML:
 *
 * <div class="siatka">
 *     <div class="komorka komorka-5"></div>
 *     <div class="komorka komorka-5"></div>
 * </div>
 */

.siatka {
    overflow: visible;
    height: 100%;
    /* Zapobiegaj zawijaniu tekstu w komórkach z inline-block */
    white-space: nowrap;
    /* Usuń spacje między komórkami */
    font-size: 0;
}

.komorka {
    position: relative;
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    width: 20%;
    height: 100%;
    /* Ustaw odstępy między komórkami */
    padding: 0 10px;
    border: 2px solid #333;
    vertical-align: top;
    /* Resetuj spacje */
    white-space: normal;
    /* Resetuj rozmiar czcionki */
    font-size: 16px;
}

/* Stany komórek */

.komorka.jest-animowana {
    background-color: #fffdec;
}

/* Wymiary komorek
   ========================================================================== */

.komorka-1 { width: 10%; }
.komorka-2 { width: 20%; }
.komorka-3 { width: 30%; }
.komorka-4 { width: 40%; }
.komorka-5 { width: 50%; }

/* Modyfikacje komorek
   ========================================================================== */

.komorka--szczegoly,
.komorka--istotne {
    border-width: 4px;
}

7. Organizacja

Odpowiednia organizacja jest istotnym elementem tworzenia każdej bazy kodu CSS. W przypadku dużych baz to wręcz kwestia kluczowa.

  • Pamiętaj o logicznym wyodrębnianiu samodzielnych fragmentów kodu.
  • Używaj osobnych plików (łączonych podczas budowania kodu) aby w prosty sposób dzielić kod na mniejsze komponenty.
  • Jeśli używasz preprocesora, powtarzające się definicje kolorów, typografii itp. przypisuj do zmiennych.

8. Przygotowanie i wdrożenie

W projektach powinno się zawsze wdrażać pewne ogólne zasady, według których kod źródłowy może być analizowany, testowany, kompresowany i wersjonowany przed wdrożeniem. Doskonałym narzędziem służącym do tego celu jest grunt autorstwa Bena Almana.

Podziękowania

Dziękuję wszystkim, którzy współtworzyli idiomatic.js. Projekt ten był dla mnie źródłem inspiracji, cytatów i wskazówek.