Zasady pisania czytelnego kodu, czyli o kulturze programisty

Czy zdarzyło ci się, że czytając cudzy kod czułeś się jak rozbitek na bezludnej wyspie? Czy błądziłeś w leśnej gęstwinie egzotycznego nazewnictwa klas, wśród ekspansji multiplikujących się divów? Czy widziałeś jak instrukcje i tagi dusiły się w zgoła nie miłosnym uścisku, rozpaczliwie potrzebując spacji niczym świeżego powietrza?

Choćbyś był Wojowniczym Żółwiem Ninja programowania, mogłoby Ci nie wystarczyć woli walki do przedarcia się przez dżunglę takiego kodu. Nawet najbardziej pasjonująca książka nie będzie nadawała się do czytania, jeśli pozbawimy ją atrybutów spacji i znaków przestankowych. Najbłyskotliwsza teoria naukowa pozostanie bezpłodna, jeśli jej suche wyliczenia nie zostaną opatrzone komentarzem objaśniającym.

Dla kogo piszesz?

Przede wszystkim, na żadnym etapie nauki programowania nie powinieneś pozwolić sobie na myślenie, że kod, który piszesz jest tylko dla Ciebie. Tworzenie kodu jest jak pisanie oficjalnego listu. Aby pozostał on czytelny, należy stosować się do pewnych bardzo ogólnych zasad tej formy komunikacji. Nasz kod jest wyrazem naszej kultury programistycznej.

Pisz czytelnie

Czytelność naszego kodu jest sprawą absolutnie elementarną i nie wymaga zbyt obszernej argumentacji. Stosując odpowiednie wcięcia w kodzie oraz spacje ułatwiamy pracę sobie oraz innym programistom czytającym czy rozwijającym nasz kod.
Dlatego powinniśmy zapoznać się z różnymi konwencjami i wybrać sobie tę, która jest dla nas najbardziej czytelna lub/i najpowszechniej używana. Warto przyzwyczajać się do szeroko stosowanych standardów, zwłaszcza na początku naszej ścieżki programisty.
Przykład odpowiednich wcięć dla kodu HTML:

 

<body>
    <section>
        <div>
            <p>Dbaj o wcięcia!</p>
            <p>
                <strong>To bardzo ważne!</strong>
            </p>
        </div>
    </section>
</body>

 

Zasada jest prosta – każdy element, który jest zagnieżdżony, musi być przesunięty w stosunku do swojego rodzica o dwie lub cztery spacje w prawo. W swoim edytorze, możemy ustawić ilość spacji, która odpowiada jednemu klawiszowi tabulacji – dzięki temu nasze wcięcia na pewno będą równe, łatwiej będzie nad nimi zapanować oraz mniej się naklikamy niż gdybyśmy za każdym razem musieli używać w tym celu spacji. Widzimy, że dzięki wcięciom nasza struktura jest przejrzysta, dlatego łatwo dostrzec relacje pomiędzy tagami:

  • <section> jest dzieckiem <body>
  • <div> jest dzieckiem <section>
  • <p> jest dzieckiem <div> i rodzeństwem dla drugiego <p>
  • <strong> jest dzieckiem <p>

Podobnie jak w kodzie HTML otwarcie każdego tagu powinno się rozpoczynać od nowej linii, tak w JavaScript każda instrukcja powinna się znajdować w oddzielnym wierszu. Tutaj wcięcia także pomagają nam zrozumieć strukturę całego kodu. Widzimy, że w ciele funkcji count, mamy zadeklarowaną zmienną lokalną num, pętlę for w której jest instrukcja warunkowa if … else.

 

var count = function() {
    var num = 6;
    for (var i = 0; i < num; i++) {
        if (i % 2 === 0) {
            console.log(i + 'parzysta');
        } else {
            console.log(i + 'nieparzysta');
        }
    }
};

 

Kolejna ważna kwestia dotyczy komentarzy. Kod JavaScript opisany odpowiednimi komentarzami będzie zawsze czytelny. Dla początkujących programistów, w ramach ćwiczenia, zaleca się opisywanie każdej linijki kodu. Z pewnością nie każda zasługuje na oddzielny komentarz, dlatego z czasem powinniśmy wyczuć, które miejsca naszego kodu są newralgiczne i które po jakimś czasie mogą nie być tak przejrzyste jak na początku. Na pewno jedną z zasad, którą powinniśmy przyjąć jest opisywanie każdej funkcji i każdego większego bloku kodu. Odpowiednie nazwy poszczególnych zmiennych czy też funkcji również są w stanie poprawić przejrzystość naszego kodu.

Bądź konsekwentny!

Trzymanie się jednej konwencji w pisaniu kodu, sprawia, że nasza praca wygląda starannie. Dlatego powinniśmy być także konsekwentni w nazewnictwie klas. Nazwy klas muszą być w języku angielskim oraz ich nazwa powinna odpowiadać ich znaczeniu na całej stronie. Podstawowe konwencje tworzenia nazw klas:

  • main_news – z podkreśleniem pomiędzy wyrazami
  • main-news – z myślnikiem oddzielającym wyrazy
  • mainNews – tzw. camelCase – kolejny wyraz jest pisany bez spacji z wielkiej litery

W nazewnictwie klas możemy stosować różne metodologie, np. OOCSS, SMACSS, Atomic czy BEM. Są one techniką organizacji klas, która pomaga zachować logiczną strukturę ich nazewnictwa. Głównie wykorzystywane przy pracy nad dużymi projektami.
Warto też wspomnieć przy okazji o identyfikatorach – unikajmy używania identyfikatorów do stylizowania elementów. Nigdy nie wiadomo, kiedy będziemy potrzebowali powtórzenia danej grupy właściwości w innym miejscu, stąd klasy są bardziej elastyczne. Identyfikatory przydadzą nam się do łatwiejszego odwołania się do danego elementu w JavaScript.

Semantyka

Kolejną zasadą zachowania czytelności i przejrzystej struktury jest całkowite oddzielenie od siebie kodu HTML, CSS i JavaScript. Dlatego style CSS piszemy w oddzielnym pliku do tego przeznaczonym oraz unikamy umieszczania zdarzeń JavaScript w kodzie HTML.

Semantyczny kod HTML wpływa na indeksowanie naszej witryny i może mieć wpływ na jej pozycjonowanie. Dzięki dobrze napisanej strukturze HTML, nasza strona będzie łatwa do przystosowania dla osób z niepełnosprawnościami a jej treść będzie czytelna także bez załadowania się pliku ze stylami.

W tym celu powinniśmy korzystać z adekwatnych oraz aktualnych tagów HTML – one bowiem, już na początkowym etapie tworzenia strony, pozwalają na określenie podstawowych funkcjonalności. Dzięki temu łatwiej nam się zorientować we własnym projekcie, co jest pomocne zwłaszcza na bardziej zaawansowanym etapie pracy.

Bądź skuteczny…

…czyli nie powtarzaj się. Don’t repeat yourself, czyli zasada DRY, podpowiada nam, że jeśli powtarzamy jakąś część kodu JavaScript lub całych grup właściwości CSS, prawdopodobnie możemy napisać to krócej i lepiej. W JavaScript przychodzą nam z pomocą np. metody i funkcje, a w CSS klasy.

Jest jeszcze jedna zasada, której stosowanie z całą pewnością uczyni nasz kod bardziej czytelnym. Jej akronim ma wdzięczną formę KISS. Keep it simple, stupid, wyraża ideę programowania prostego i przejrzystego. Czasem lepiej powtórzyć jakiś kawałek kodu, jeśli ceną za zastosowanie DRY, czy innych bardziej złożonych zasad, ma być nadmierne komplikowanie kodu.

Akurat w tym aspekcie wygląd ma znaczenie – pisząc kod prosty i uporządkowany okazujemy moc naszej kultury programistycznej. Dzięki temu, nawet jeśli będziemy popełniać błędy (a będziemy), znacznie łatwiej będzie nam je zlokalizować.

Site Footer

Sliding Sidebar