C# / .NET Kompendium PLEN
.NET / C# / SOLID, Clean Code, DI

Clean Code - czysty kod

Clean Code to zbiór zasad i praktyk pisania kodu, który jest czytelny, zrozumiały i łatwy w utrzymaniu - nie tylko dla komputera, ale przede wszystkim dla ludzi, którzy będą go czytać i modyfikować (włącznie z Tobą za pół roku). Termin spopularyzował Robert C. Martin w książce "Clean Code" (2008).

Kluczowa idea: kod czyta się dużo częściej niż się go pisze, więc optymalizacja pod czytelność się opłaca.

Główne zasady

1. Nazewnictwo ma znaczenie

Nazwy zmiennych, funkcji i klas powinny jasno mówić, co robią - bez potrzeby komentarza.

// Źle
var d = 30; // dni do wygaśnięcia
decimal Calc(decimal a, decimal b) => a * b * 0.23m;

// Dobrze
var daysUntilExpiration = 30;
decimal CalculateVatAmount(decimal netPrice, decimal quantity)
{
    return netPrice * quantity * VAT_RATE;
}

2. Funkcje robią jedną rzecz i są krótkie

Jeśli funkcja ma nazwę z "i" ("PobierzIZapisz") albo trzeba przewijać, żeby ją przeczytać - to sygnał, że robi za dużo.

// Źle - funkcja robi 3 różne rzeczy
public async Task ProcessOrder(Order order)
{
    // walidacja
    if (order.Items.Count == 0) throw new Exception("empty");
    // zapis do bazy
    await db.Orders.InsertAsync(order);
    // wysyłka maila
    await mailer.Send(order.CustomerEmail, "Potwierdzenie");
}

// Dobrze - rozbite na czytelne kroki
public async Task ProcessOrder(Order order)
{
    ValidateOrder(order);
    await SaveOrder(order);
    await SendConfirmationEmail(order);
}

3. Unikaj duplikacji (DRY - Don't Repeat Yourself)

Powtarzający się kod to miejsce, gdzie błąd trzeba będzie poprawić w wielu miejscach naraz.

4. Komentarze tłumaczą "dlaczego", nie "co"

Dobry kod sam mówi co robi. Komentarz ma sens tam, gdzie trzeba wyjaśnić decyzję, która nie jest oczywista z samego kodu.

// Źle - komentarz opisuje oczywisty kod
// zwiększ licznik o 1
counter++;

// Dobrze - komentarz tłumaczy nieoczywisty powód
// Retry z opóźnieniem, bo API hub.ag3nts.org czasem zwraca 429
// przy równoległych requestach z wielu agentów
await Task.Delay(1000);

5. Małe klasy/moduły z jasną odpowiedzialnością

To w zasadzie SOLID w pigułce - każdy moduł powinien mieć jeden, jasny powód istnienia (patrz Single Responsibility Principle, o którym rozmawialiśmy przy SOLID).

6. Obsługa błędów jest częścią logiki, nie dodatkiem

// Źle - błąd ginie po cichu
try
{
    await agent.Run();
}
catch (Exception e)
{
    Console.WriteLine("error");
}

// Dobrze - błąd jest widoczny i informacyjny
try
{
    await agent.Run();
}
catch (Exception error)
{
    logger.Error($"Agent {agent.Name} failed: {error.Message}", error);
    throw new AgentExecutionException(agent.Name, error);
}

7. Konsystencja i formatowanie

Jeden styl w całym projekcie (stąd popularność ESLint/Prettier w JS, StyleCop/EditorConfig w C#) - mniej "szumu" wizualnego, mózg nie musi się przestawiać między konwencjami.

Test na "czysty kod"

Kilka pytań pomocniczych, które warto sobie zadać patrząc na kod: - Czy ktoś inny (albo ja za 3 miesiące) zrozumie to bez tłumaczenia? - Czy nazwa funkcji mówi dokładnie to, co ona robi - nic więcej, nic mniej? - Czy mógłbym to przetestować bez owijania połowy aplikacji mockami? - Czy zmiana w jednym miejscu nie wymusza zmian w pięciu innych?


Clean Code i SOLID mocno się przenikają - SOLID to bardziej reguły strukturalne (jak dzielić odpowiedzialności między klasy/moduły), a Clean Code to szerszy zestaw praktyk na poziomie stylu i czytelności pojedynczych funkcji, nazw, komentarzy.

Postaw mi kawę