Czysty kod #1

Artykuł jest aktualny

Dbam o aktualność moich najpopularniejszych artykułów, abyś otrzymał/a najwyższej jakości wiedzę.
~ 2020

Jest to pierwszy artykuł dotyczący zasad czystego kodu. W tej części przedstawię spojrzenie na nadawanie znaczących nazw oraz używanie komentarzy. 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 nie znaczą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.

Pamiętaj!

Pisz kod tak, aby ktoś, kto obejrzy go po Tobie, bez problemu zrozumiał jego działanie.

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);
}

Pamiętaj!

Użyte nazwy zmiennych, metod, klas itd. powinny jednoznacznie odzwierciedlać ich przeznaczenie.

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.

Nie dodawaj komentarza do kodu, który sam się opisuje.

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.

Pamiętaj!

Pisz kod taki jakim chciałbyś go zastać.

Newsletter

Zapisz się do mojego newslettera, aby nie przegapić nowych postów.

Dodatkowo wyślę Ci darmowego ebooka mojego autorstwa zawierającego mnóstwo wskazówek dla programisty aplikacji mobilnych.

3 Komentarze. Zostaw komentarz

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *

Wypełnij to pole
Wypełnij to pole
Proszę wprowadzić prawidłowy adres email.
You need to agree with the terms to proceed

Menu