Co jakiś czas mam do czynienia z różnymi starszymi projektami napisanymi przez inne osoby. Jedną z bardziej irytujących mnie rzeczy są „magiczne” cyferki. Może jest ktoś (oprócz autora), kto patrząc na poniższy fragment kodu będzie wiedział jakich dokładnie użytkowników zwraca metoda getUzytkownicy()? Niestety ja się do takich osób nie zaliczam.

class Uzytkownik extends AppModel
{
    public function getUzytkownicy() {
        return $this->find('all', array(
            'conditions' => array(
                'Uzytkownik.status' => array(2, 3)
            )
        ));
    }
}

Fragment kodu jest wzorowany na klasie modelu dla CakePHP 1.3, ale pokazany problem jest niezależny od szkieletu programistycznego lub jego braku – to brak czytelności. Nie znająć frameworka z kodu można odczytać, że zwraca on kolekcję obiektów użytkowników o statusach… no właśnie – 2 i 3. Co to znaczy? To najczęściej wie autor i osoby, które musiały już tego poszukać. Pozostali dopiero będą szukali znaczenia tytułowych cyferek. Najczęściej w takich sytuacjach brakuje również komentarza, czy to wewnątrz metody czy PHPDoc dla metody.

Prywatnie rozwiązuję powyższy problem w taki sposób:

class Uzytkownik extends AppModel
{
    const STATUS_NIEPOTWIERDZONY = 1;
    const STATUS_POTWIERDZONY = 2;
    const STATUS_ZABLOKOWANY = 3;
    const STATUS_USUNIETY = 4;
    
    /**
     * Zwraca tablice uzytkownikow potwierdzonych i zablokowanych
     * @return array
     */
    public function getUzytkownicy() {
        return $this->find('all', array(
            'conditions' => array(
                'Uzytkownik.status' => array(
                    self::STATUS_POTWIERDZONY, 
                    self::STATUS_ZABLOKOWANY
                )
            )
        ));
    }
}

Kod z drugiego fragmentu jest o wiele bardziej czytelny i klarowny. Przede wszystkim nie wymaga dodatkowego przeszukiwania kodu i aplikacji, żeby dowiedzieć się co oznaczają poszczególne numery statusów – nazwa stałej jest wystarczająco jasna. Dobrym pomysłem jest również pisanie komentarzy dla metod i późniejsze ich utrzymywanie. Dlaczego utrzymywanie? Ponieważ jeżeli statusy w zapytaniu zostaną zmienione a komentarz nie to będzie wprowadzał w błąd podczas programowania (IDE wyświetli w podpowiedziach metod tylko treść komentarza). W takim wypadku można by stwierdzić, że brak komentarza dla metody jest lepszy niż błędy komentarz – przy braku będziemy się sugerować nazwą lub zajrzymy do kodu, żeby sprawdzić działanie.

Dodatkową kwestią jest też nazwa metody: getUzytkownicy(), można by ją zastąpić getPotwierdzeniIZablokowaniUzytkownicy(). Jednak w tym momencie nazwa metody robi się już trochę długa. Prywatnie metody tego typu staram się nazywać raczej odnosząc się do miejsca lub kontekstu ich wykorzystania. Na przykład getListaUzytkownikowDlaAdm(). Taka nazwa również jest dość długa, ale pozwala dużo lepiej zidentyfikować zastosowanie metody. Dodatkowo w jednej z aplikacji, które rozwijam/utrzymuję obiekt odwzorowujący proces ma 18 statusów wskazujących na różne etapy procesu. Tworząc metodę, której nazwą byłby zlepek np. nazw 6 statusów (których nazwy mogą i często są wieloczłonowe), które powinny mieć obiekty pokazywane na liście byłoby pomyłką.

Podsumowując mam mały apel:

• nazywajmy klasy/metody/stałe/zmienne/etc w sposób bardziej odzwierciedlający to co robią;
• piszmy i utrzymujmy komentarze (najlepiej PHPDoc, żeby można było z nich korzystać poprzez IDE i wygenerować dokumentację);
• nie używajmy „magicznych” cyferek tylko stałych.

Dziękuję 🙂