Czysty kod #1

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 naszego kodu w czystoś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.


cytat1


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, więc skoro wiemy, że parametr y niesie ze sobą rok urodzenia do sprawdzenia, to od razu zmieniamy 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 czysty! Odnieśliśmy zwycięstwo! 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);
     
}

cytat2


Po tych zabiegach dokładnie wiemy co się dzieje w każdej linii tego kodu.

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 AddOrders(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ójrzmy na kod poniżej:


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. Osoba, która będzie czytała taki zostawiony przez nas kod za kilka lat będzie zastanawiała dlaczego kod został zakomentowany. Zada sobie serie 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.

Na koniec pozostawiam Ci złotą zasadę:


cytat3


Mam coś dla Ciebie

Zapisz się do mojego newslettera, a ja prześlę Ci zbiór kilkunastu praktycznych wskazówek dla programisty aplikacji mobilnych.

Menu