Styl i czytelność kodu, konwencje kodowania

1. Wprowadzenie

W programowaniu styl to nie kwestia mody, lecz przetrwania. Java to język, w którym pracują ogromne zespoły i jeśli każdy będzie pisał „jak przywykł”, projekt szybko zamieni się w zbiór niespójnych kawałków, w których odnajdzie się tylko autor (i to nie zawsze).

Styl kodu to zbiór zasad, które sprawiają, że kod jest jednakowo czytelny dla wszystkich. To jak znaki drogowe: jeśli je ignorować, ruch szybko zamieni się w chaos.

Dlaczego to ważne?

• Czytelność: kod czyta się częściej, niż pisze. Zły styl jest jak nieczytelny charakter pisma lekarza — nikt nie odczyta, co tam jest.
• Utrzymywalność: jeśli kod jest napisany zgodnie z zasadami, łatwiej go zmieniać i mniejsze jest ryzyko przypadkowego popsucia czegoś.
• Współpraca: w zespole wszyscy powinni rozumieć się bez zbędnych pytań.
• Narzędzia: autoformatery i analizatory kodu działają lepiej, gdy styl jest spójny.

2. Główne błędy stylu kodu (i jak ich unikać)

Nieprzestrzeganie wcięć i nawiasów

Błąd:
Kod bez wcięć i z chaotycznymi nawiasami jest udręką dla oczu i mózgu.

if(x>0){
System.out.println("x jest dodatni");
}else{
System.out.println("x nie jest dodatni");
}

Jak należy:

if (x > 0) {
    System.out.println("x jest dodatni");
} else {
    System.out.println("x nie jest dodatni");
}

Komentarz:
Używaj czterech spacji dla każdego poziomu zagnieżdżenia (to standard Javy). Tabulacja jest złem, chyba że cały zespół uzgodni inaczej.

Nieprawidłowe nazwy zmiennych, metod i klas

Błąd:

int a = 5;
String s = "John";
void f() { /* ... */ }

Jak należy:

int age = 5;
String userName = "John";
void printReport() { /* ... */ }

Komentarz:
Nazwy powinny być znaczące i odzwierciedlać istotę zmiennej lub metody.

• Klasy — wielką literą, CamelCase: UserAccount.
• Metody i zmienne — małą literą, camelCase: calculateSalary, userList.

Zbyt długie metody i klasy

Błąd:
Metoda na 100 wierszy, klasa na 1000 wierszy — prawdziwy nightmare mode dla utrzymania.

Jak należy:
Każda metoda powinna robić jedną rzecz i być krótka (idealnie — mieścić się na ekranie). Klasy też nie powinny rozrastać się do rozmiarów „Wojny i pokoju”.

Przykład:

Źle:

public void processOrder() {
    // 200 wierszy kodu
}

Dobrze:

public void processOrder() {
    validateOrder();
    calculateTotal();
    saveToDatabase();
    sendEmailConfirmation();
}

Używanie „magicznych liczb” i ciągów

Błąd:

if (status == 42) {
    // ...
}

Jak należy:

public static final int STATUS_APPROVED = 42;

if (status == STATUS_APPROVED) {
    // ...
}

Komentarz:
Zamiast „magicznych” liczb i ciągów używaj stałych (static final). W nowszych wersjach Javy są też enum — używaj ich dla ograniczonych zbiorów wartości.

Komentarze: brak albo nadmiar

Błąd 1:
Brak komentarzy w ogóle — nie wiadomo, co robi złożony kod.

Błąd 2:
Komentarze do każdej czynności, nawet oczywistej.

// Zwiększamy x o 1
x = x + 1;

// Sprawdzamy, czy x równa się 10
if (x == 10) {
    // ...
}

Takie komentarze tylko przeszkadzają! Komentuj tylko złożone lub nieoczywiste miejsca. A w ogóle dobry kod powinien być zrozumiały bez komentarzy — komentarze służą do wyjaśnienia „dlaczego”, a nie „co”.

// Uwzględniamy rabat dla klientów VIP
double total = calculateTotalWithDiscount();

3. Konwencje w Javie: jak piszą profesjonaliści

W Javie istnieją oficjalne i de facto standardy formatowania kodu. Oracle Java Code Conventions i Google Java Style Guide — to najpopularniejsze.

Wcięcia i nawiasy

Otwierający nawias klamrowy stawia się w tym samym wierszu co deklaracja:

public void print() {
    // ...
}

Zagnieżdżenie — cztery spacje.

Nazewnictwo

• Klasy i interfejsy: CamelCase wielką literą (Person, UserAccount).
• Metody i zmienne: camelCase małą literą (calculateSalary, userList).
• Stałe: WIELKIE_LITERY_Z_PODKREŚLENIEM (MAX_SIZE, DEFAULT_TIMEOUT).
• Pakiety: tylko małe litery, mogą być z kropkami (com.example.project).

Spacje

Spacje wokół operatorów i po przecinkach:

int sum = a + b;
System.out.println(name, age);

Nie wstawiaj spacji po nawiasie otwierającym ani przed nawiasem zamykającym:

if (x > 0) { ... }

Długość wiersza

Zaleca się nie przekraczać 100–120 znaków w wierszu. (Tak, tak, monitor jest ogromny, ale kod i tak czyta się lepiej, gdy nie ucieka w horyzont).

Kolejność deklaracji członków klasy

Zalecana kolejność (wg Oracle):

1. Pola (najpierw statyczne, potem zwykłe)
2. Konstruktory
3. Metody

Przykład:

public class User {
    private static int userCount;
    private String name;

    public User(String name) {
        this.name = name;
        userCount++;
    }

    public String getName() {
        return name;
    }
}

4. Przykład: refaktoryzacja złego stylu

Oto przykład klasy, którą można spotkać na wolności:

class person{String n;int a;void p(){System.out.println(n+" "+a);}}

Gdzieś w biurze od tego kodu płacze jeden programista Java.

Poprawmy go:

public class Person {
    private String name;
    private int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public void print() {
        System.out.println(name + " " + age);
    }
}

Co się zmieniło:

• Klasa i jej członkowie mają właściwe modyfikatory dostępu.
• Nazwy są znaczące i czytelne.
• Każdy członek klasy w nowym wierszu.
• Użyto konstruktora do inicjalizacji.
• Pola private, aby zachować enkapsulację.

5. Praktyczne niuanse

Autoformatery

Nowoczesne IDE (IntelliJ IDEA, Eclipse, VS Code) potrafią automatycznie formatować kod zgodnie ze standardem.

Skróty klawiaturowe:

• IntelliJ IDEA: Ctrl + Alt + L
• Eclipse: Ctrl + Shift + F

Analiza statyczna

Narzędzia takie jak Checkstyle, SonarLint, PMD pomagają wykrywać naruszenia stylu i potencjalne błędy jeszcze przed uruchomieniem programu.

Jak to wygląda:

• Checkstyle zgłosi zastrzeżenia, jeśli masz zmienną o nazwie x zamiast userAge.
• SonarLint podpowie, jeśli metoda jest zbyt długa albo klasa narusza zasady SOLID.

Podział odpowiedzialności i „czysty” kod

• Każda klasa powinna odpowiadać tylko za jedno zadanie (Single Responsibility Principle).
• Nie bój się tworzyć dodatkowych klas i metod — to nie „przerost”, lecz troska o przyszłego czytelnika.
• Unikaj duplikacji kodu: jeśli widzisz dwa podobne fragmenty — wyodrębnij je do osobnej metody.

Stałe i „magiczne liczby”: jak to robić dobrze

Zamiast:

double price = 100 * 0.18;

Lepiej:

public static final double VAT_RATE = 0.18;
double price = 100 * VAT_RATE;

A jeśli często pojawiają się z góry określone zbiory wartości — używaj enum:

public enum Status {
    NEW, IN_PROGRESS, DONE
}

6. Typowe błędy w stylu i czytelności kodu

Błąd nr 1: Ignorowanie konwencji kodowania.
Jeśli w zespole nie ma jednolitego stylu, kod szybko staje się nieczytelny i trudny w utrzymaniu. Nawet jeśli piszesz samodzielnie, za rok sam sobie podziękujesz.

Błąd nr 2: Zbyt krótkie/długie nazwy.
Zmienna a lub temp — to źle. Zmienna theCurrentUserNameThatIsUsedForAuthorizationInTheSystem — też nie. Znajdź balans: userName, age, bookList.

Błąd nr 3: „Magiczne liczby”.
Wstawianie liczb i ciągów bezpośrednio do kodu utrudnia utrzymanie i zwiększa ryzyko błędów.

Błąd nr 4: Ogromne metody i klasy.
Im większa metoda, tym trudniej ją testować i rozumieć. Dziel na logiczne części.

Błąd nr 5: Zła struktura klasy.
Pola są rozrzucone gdzie popadnie, metody zadeklarowane w przypadkowej kolejności — to wszystko utrudnia szybkie znalezienie właściwego miejsca.

Błąd nr 6: Nadmiarowe lub brakujące komentarze.
Komentarz „inicjalizacja zmiennej” obok int x = 0; nie jest potrzebny. Komentarz wyjaśniający złożoną logikę biznesową — jest bardzo potrzebny.

Błąd nr 7: Niespójne formatowanie.
W jednej części projektu — cztery spacje, w innej — tabulacja, tu nawiasy w nowym wierszu, tam — w tym samym. Wygląda to niechlujnie i irytuje kolegów.