Jak dbać o czysty kod w projekcie?
Lista najlepszych praktyk, które pomogą Ci pisać czysty kod.
Czym jest ten czysty kod i dlaczego powinniśmy dążyć do utrzymania jego odpowiedniej jakości?
Znaczące nazwy
Zacznijmy od nazw zmiennych. Zastanów się, co jest nie tak z kodem przedstawionym poniżej.
public bool Calculate (int y)
{
int x = 18;
int temp = DateTime.Now.Year - y;
return (temp >= x);
}
Po chwili spędzonej na analizie widzimy, że na pewno coś jest tu liczone i w zależności od warunku funkcja zwraca prawdę lub fałsz. Są tu użyte nic nieznaczące nazwy. Co oznacza x? Jaką informację niesie ze sobą parametr y i o chodzi z tą nazwą temp? Jeżeli autor tego kodu przedstawiłby nam logikę działania tej funkcji, nie mielibyśmy problemów z korzystaniem z tej funkcji, aczkolwiek nie na tym polega pisanie czystego kodu.
Zastanówmy się, co możemy poprawić w tym kodzie, aby był on czystszy. Funkcja ta zwraca informację o tym, czy różnica pomiędzy aktualnym rokiem a rokiem przekazanym do funkcji jest większy od 18 (po odpowiedniej refaktoryzacji będziemy mogli użyć tej funkcji w systemie do sprawdzania pełnoletności użytkowników).
Dobrze, skoro wiemy, że parametr y niesie ze sobą rok urodzenia do sprawdzenia, to zmieńmy jego nazwę na birthYear (dobrą praktyką jest stosowanie angielskich nazw kodzie i skracanie ich, jeżeli jest to możliwe i nie zaburza czytelności nadanej nazwy). Wartość 18 oznacza nasz warunek pełnoletności, więc proponuję nazwę adultAge. Wynikiem wyrażenia DateTime.Now.Year – y jest różnica pomiędzy latami – nadajmy tu nazwę yearDiff. Spójrzmy teraz na kod po naszych poprawkach:
public bool Calculate(int birthYear)
{
int adultAge = 18;
int yearDiff = DateTime.Now.Year - birthYear;
return (yearDiff >= adultAge);
}
Kod jest znacznie czystszy! Odnieśliśmy zwycięstwo! Jednak nie tak szybko. Spójrzmy na nazwę funkcji. Nazwa Calculate jest prawidłowa w tym sensie, że funkcja „coś tam liczy”, ale jej nazwa powinna opisywać jej zadanie. Odpowiednią nazwą może być IsAdult (dla funkcji, które zwracają wartość bool dodaje się przedrostek Is)
public bool IsAdult(int birthYear)
{
int adultAge = 18;
int yearDiff = DateTime.Now.Year - birthYear;
return (yearDiff >= adultAge);
}
Po tych zabiegach dokładnie wiemy, co się dzieje w każdej linii tego kodu.
Czyty kod i komentarze
O komentarzach można napisać kilkustronicowy artykuł, aczkolwiek chciałbym przedstawić kilka najważniejszych zasad, które pomogą Ci korzystać z komentarzy, w sposób prawidłowy.
Czy rzeczywiście poniższy kod wymaga komentarza?
//Dodaje zlecenie do listy
public void AddOrder (Order order)
{
_orders.Add (order);
}
Dzięki użyciu odpowiednich nazw metody oraz zmiennych widzimy, że metoda ta dodaje zlecenie do listy. W tym przypadku komentarz jest kompletnie zbędny i zakłóca czytelność kodu.
Komentarze powinny być krótkie i zawierać najistotniejsze informacje.
Pamiętaj, aby nie wykorzystywać funkcjonalności komentarzy jako notatnika. Jeżeli chcesz opisać dany fragment kodu, zrób to krótko i na temat. Natomiast jeżeli napisany kod do zrozumienia wymaga komentarza większego niż on sam, zastanów się, czy kod nie wymaga poprawek.
Zakomentowany kod.
Spójrz na poniższy kod.
var formatted = OrdersHelper.FormatRichTextFromOrder(order, commisionData, headers);
for (int idx = 0; idx < formatted.Length; idx++)
{
// Orders.Instance.SetValue(idx);
// MessageFormatted[idx] = text;
if (headers.Count > 0)
{
Header[idx] = headers[idx];
}
}
Zostawianie zakomentowanego kodu jest jedną z najgorszych praktyk i źle świadczy o programiście, który się tego dopuszcza. Za jakiś czas, gdy inny programista będzie analizował ten kod, istnieje szansa, że zada sobie serię pytań: Czy mogę to usunąć? Może kod ten został zakomentowany, w ramach testów?
Koniec końców osoba taka zostawi kod w tej postaci, przez co w przyszłości kolejne osoby będą głowiły się nad przeznaczeniem tych instrukcji. Nikt nie powiedział, że sami na niego nie natrafimy.
Złota zasada na koniec.
