Rozdział 2 - Komentarze i formatowanie kodu - Formatowanie kodu i najlepsze praktyki

Pisząc kod musimy zwrócić uwagę na to, czy jest on czytelny.

W Javie, podobnie jak w wielu innych językach programowania, białe znaki nie robią dla kompilatora różnicy. Dzięki temu możemy w dowolny sposób operować nimi w celu poprawy czytelności, a co za tym idzie, także jakości kodu.

Spójrzmy ponownie na nasz pierwszy program, zapisany w inny sposób:

public class HelloWorld {public static void main(String[] args) {System.out.println("Witaj Swiecie!");}}

Powyższa wersja programu działa tak samo, jak poniższa:

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Witaj Swiecie!");
  }
}

Kompilator nie ma problemu z kodem źródłowym z pierwszego z powyższych przykładów pomimo, że dla programisty jest on nieczytelny.

Czy w praktyce ma to aż takie duże znaczenie? Wyobraźmy sobie, że pracujemy nad programem, który ma pół miliona linii kodu. Jeżeli jego autorzy nie dbają o kod źródłowy, to jego utrzymanie, zrozumienie, oraz rozwój, będą bardzo trudne i, co najgorsze, nieprzyjemne.

Powinniśmy zawsze stosować przywilej używania białych znaków (spacji, tabulacji i nowych linii) w celu zapisania kodu naszego programu w taki sposób, by był on czytelny i zrozumiały – zarówno dla nas, jak i innych osób, które potencjalnie będą nasz kod czytać i utrzymywać.

Często zdarza się, że programista, analizując swój kod w celu poprawy błędu lub wprowadzeniu modyfikacji, nie pamięta, dlaczego napisał taki, a nie inny kod, zaledwie tydzień wcześniej.

Utrzymywanie czystego kodu służy nie tylko ułatwienia współpracy z innymi programistami, ale także ułatwieniu pracy sobie.

Po napisaniu kodu warto spojrzeć na niego i zastanowić się, czy:

  • po przeczytaniu go tydzień bądź miesiąc później, będziemy rozumieli, co i dlaczego robi?
  • czy inny programista patrząc na nasz kod będzie rozumiał, dlaczego napisaliśmy go w taki, a nie inny sposób?

Najlepsze praktyki i konwencje

W związku z tworzeniem programów, często możemy usłyszeć o tzw. najlepszych praktykach (best practices), bądź też o różnych konwencjach programistycznych.

Zwracają one uwagę na przeróżne aspekty związane z pisaniem kodu źródłowego, jak i ogólnie z procesem wytwarzania oprogramowania. Niektóre z nich są mniej, inne bardziej popularne, część się nawzajem wyklucza, inne natomiast znajdują zastosowanie tylko w konkretnych językach programowania bądź rodzajach pisanych programów.

Najlepsze praktyki i konwencje programistyczne mają na celu m. in.:

  • podwyższanie jakości wytwarzanego oprogramowania,
  • zachowywanie spójności w kodzie źródłowym,
  • zwiększanie czytelności kodu źródłowego,
  • dbanie o to, by kod spełniał przyjęte wytyczne i standardy.
Ilu programistów, tyle najlepszych praktyk. Są różne konwencje, które są mniej lub bardziej popularne. Ważne jest, aby pracując na nowym projekcie stosować się do standardów (oraz formatowania kodu), które jest na nim używane, o ile nie narusza ono pewnych ogólnoprzyjętych standardów.

Z czasem (także w kolejnych rozdziałach tego kursu), poznasz bardzo wiele standardów, konwencji i najlepszych praktyk. Dobrze jest sobie wyrobić własne zdanie na ich temat, a także znaleźć swój własny styl, który będzie dla Ciebie wygodny. Pamiętaj jednak, by mieć na względzie inne osoby, z którymi będzie pracować.

Pamiętajmy – to, jak i jaki kod piszemy, świadczy o nas! Jeżeli będziemy pisali dobry i czytelny kod, to będziemy uznawani za lepszych programistów.

W kolejnych podrozdziałach opisanych zostało kilka najlepszych praktyk związanych z formatowaniem kodu, które warto stosować od samego początku nauki programowania, aby weszły w nawyk.

Na temat najlepszych praktyk związanych z tworzeniem kodu można znaleźć wiele książek, jedną z których jest "Clean Code", autorem której jest Robert C. Martin.

Jedna instrukcja na linię

Umieszczanie więcej niż jednej instrukcji w jednej linii powoduje, że kod jest nieczytelny:

public class HelloWorldFormatowanie {
  public static void main(String[] args) {
    System.out.println("Witaj"); System.out.println("Swiecie!");
  }
}

Zamiast tego, powinniśmy umieszczać po jednej instrukcji na linię:

public class HelloWorldFormatowanie {
  public static void main(String[] args) {
    System.out.println("Witaj");
    System.out.println("Swiecie!");
  }
}
W jednej linii umieszczamy jedną instrukcję.

Stosowanie wcięć

Wszystkie bloki kodu powinny mieć wcięcia w zależności od poziomu, na którym się znajdują.

Są różne konwencje odnośnie rodzaju i ilości białych znaków używanych do robienia wcięć w kodzie na każdy poziom bloku kodu, np.:

  • stosowany jest znak tabulacji (\t),
  • stosowane są cztery znaki spacji,
  • stosowane są dwa znaki spacji.
Wcięcie w kodzie wstawiamy za pomocą przycisku Tab na klawiaturze.
Przykłady w tym kursie będą zazwyczaj miały wcięcia złożone z dwóch znaków spacji.

W poniższym przykładzie pierwsza linia definiuje klasę HelloWorld – na początku nie ma wcięcia, ponieważ klasa ta jest na najwyższym poziomie, tzn. nic jej nie otacza.

Metoda main ma pojedyncze wcięcie (składające się z dwóch spacji), ponieważ zawarta jest w klasie.

Instrukcja wypisująca tekst na ekran ma dwa wcięcia, ponieważ jest wewnątrz metody, która jest z kolei wewnątrz klasy – stąd dwa poziomy wcięć. Wkrótce poznamy kolejne "bloki" kodu, które będziemy poprzedzać jeszcze większa liczbą wcięć.

Poniższy przykład ilustruje poziomy wcięć w naszym pierwszym programie:

public class HelloWorld {
// jedno wciecie (z dwoch spacji) przed metoda main
  public static void main(String[] args) {
    // dwa wciecia (po dwie spacje kazde) przed ponizsza instrukcja
    System.out.println("Witaj");
  } // jedno wciecie przed nawiasem konczacym cialo metody main
}
Każdą linię w kodzie poprzedzamy odpowiednim wcięciem, którego poziom zależny jest od tego, iloma blokami jest poprzedzony. Każdy blok kodu ma o jeden poziom wcięć więcej, niż blok, który go otacza.

Nazwy-wielbłądy (czyli Camel Case)

Camel Case to nazwa konwencji pisania ciągów tekstowych, w których kolejne wyrazy rozpoczynamy od wielkiej litery:

toJestPrzykladNazwyStosujacejCamelCase

Inną, często stosowaną konwencją, jest rozdzielanie kolejnych słów za pomocą podkreślenia, np.:

to_jest_przyklad_nazwy_stosujacej_pokreslenia

W Javie stosuje się zazwyczaj Camel Case.

Nazwy klasy także stosują Camel Case, z tym wyjątkiem, że pierwszy wyraz w nazwie także zapisany jest wielką literą.

Jeżeli nie będziemy stosować Camel Case, nasze nazwy będą wyglądać jak poniżej i będą nieczytelne:

dluganazwawktorejniewiadomoocochodzi
Stosujmy Camel Case w naszych kodach źródłowych – każdy wyraz, poza pierwszym (wyjątek – nazwa klasy), powinien zaczynać się z wielkiej litery.

Nazwy klas zaczynamy wielką literą

Nazwy klas powinny zawsze zaczynać się wielką literą – dla przykładu, klasa w naszym pierwszym programie nazywała się HelloWorld.

Nazwy klas zawsze zaczynamy wielką literą, a pozostałą część nazwy piszemy zgodnie z konwencją Camel Case.

Nie trzymamy zakomentowanego kodu

Często pisząc kod będziemy chcieli na chwilę "wyłączyć" fragment kodu, otaczając go komentarzem wielolinijkowym /* ... */. O ile jest to przydatne na chwilę, to w finalnej wersji kodu nie powinniśmy przetrzymywać zakomentowanych fragmentów, gdyż zmniejszają one czytelność kodu.

Inni programiści, napotykając taki kod, nie będą pewni, czy kod ten jest w jakiś sposób istotny, czy nie, więc prawdopodobnie pozostawią go tam. Zdarza się, że zakomentowany kod potrafi zalegać w kodzie źródłowym przez lata. Lepszym stwierdzeniem byłoby wręcz, iż zakomentowany kod zaśmieca kod źródłowy.

public class HelloWorldZakomentowanyKod {
    public static void main(String[] args) {
        System.out.println("Witaj Swiecie!");

        /* moze to bedzie potrzebne jeszcze kiedys? zostawilem na wszelki wypadek
        System.out.println("Witajcie!");
        */
    }
}
Nie zostawiajmy w napisanym przez nas kodzie źródłowym zakomentowanych bloków kodu – powodują one zmniejszenie czytelności kodu.

Nazwy obiektów oraz komentarze po angielsku

Pisząc nasz kod źródłowy na komercyjnym projekcie, zawsze powinniśmy stosować język angielski – zarówno w nazwach zmiennych, metod, klas itd., jak i w komentarzach – taka jest ogólnoprzyjęta zasada – wiele osób, z którymi będziemy pracować, nie będzie znała języka polskiego.

Tą zasadę naruszamy w tym kursie ze względu na to, że dopiero uczymy się programować.

W pracy zawsze powinniśmy stosować w kodzie źródłowym język angielski.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Nie musisz podawać swojego imienia, e-mailu, ani strony www, aby opublikować komentarz. Komentarze muszą zostać zatwierdzone, aby były widoczne na stronie.