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.