Refaktoryzacja może ograniczyć duplikację, a mimo to utrudnić wprowadzanie zmian, jeśli dodaje niejasne abstrakcje lub przenosi złożoność w inne miejsce. Aby ocenić jej rezultat, nie wystarczy porównać wyniku punktowego ani sprawdzić, czy testy przechodzą: trzeba określić, co ma się poprawić, obserwować kilka sygnałów i ocenić, czy system łatwiej modyfikować.
Ten poradnik wyjaśnia, jak mierzyć łatwość utrzymania aplikacji PHP przed refaktoryzacją i po niej, nie zamieniając metryk w odizolowane cele. Metodę można stosować do klasy, modułu lub przepływu biznesowego, pod warunkiem porównania tego samego zakresu i odnotowania kontekstu.
Dlaczego pojedyncza metryka nie dowodzi łatwości utrzymania
Łatwość utrzymania to zdolność do zrozumienia, testowania i modyfikowania systemu przy akceptowalnym poziomie ryzyka. Żaden pojedynczy wskaźnik nie odzwierciedla samodzielnie tych zdolności. Mniej linii nie musi oznaczać mniejszej złożoności; większe pokrycie nie gwarantuje przydatnych testów; a korzystny wynik analizy statycznej nie pokazuje, czy zespół rozumie projekt.
Ponadto metryki mogą się zmieniać z przyczyn niezwiązanych z refaktoryzacją: po aktualizacji narzędzia, zmianie reguł analizy, zmianie zakresu albo uwzględnieniu w raporcie wygenerowanego kodu. Dlatego każdą wartość należy interpretować wraz z metodą jej obliczania, analizowanym obszarem i znanymi ograniczeniami.
Celem nie jest abstrakcyjne udowodnienie, że zmiana „ulepszyła kod”. Chodzi o sprawdzenie, czy rozwiązała konkretny problem bez wprowadzania nieproporcjonalnego ryzyka.
Określ, jaką zdolność do wprowadzania zmian chcesz poprawić
Przed pomiarem sformułuj weryfikowalną hipotezę o jasno określonym zakresie. Na przykład: „Oddzielenie reguł obliczeń od tej klasy powinno umożliwić ich testowanie bez uruchamiania przepływu HTTP” albo „Ograniczenie zależności tej usługi powinno zmniejszyć liczbę zmian potrzebnych do dodania reguły”. Hipoteza wskazuje oczekiwany rezultat, a nie narzuca architektury wyłącznie dlatego, że jest modna.
Określ obszar i operacje, których dotyczy zmiana: klasy, endpointy, polecenia, joby lub reguły biznesowe. Zapisz też, co pozostaje poza zakresem, na przykład integracja zewnętrzna lub znany dług techniczny, którym nie będziesz się zajmować. Bez takiego zakresu porównanie może mieszać efekty refaktoryzacji z innymi zmianami.
Warto przełożyć hipotezę na praktyczne obserwacje. Czy łatwiej będzie znaleźć regułę? Czy będzie można ją przetestować bez rzeczywistej bazy danych? Czy zmniejszy się liczba modułów wymagających modyfikacji przy typowej zmianie? Wybierz kilka pytań, na które zespół może odpowiedzieć na podstawie dowodów.
Ustal pomiar bazowy przed zmianą kodu
Zapisz stan początkowy dla możliwej do zidentyfikowania rewizji repozytorium, używając tych samych narzędzi i konfiguracji, których użyjesz później. W przypadku obszaru PHP warto połączyć następujące sygnały:
- Złożoność: przejrzyj rozbudowane metody, gałęzie warunkowe i miejsca, w których kumulują się decyzje. Złożoność cyklomatyczna może być wskazówką, ale sama nie opisuje trudności w zrozumieniu reguły.
- Sprzężenie: zidentyfikuj bezpośrednie zależności, pomieszane odpowiedzialności i powiązania z infrastrukturą. Sprawdź, czy modyfikacja wymaga poznania lub zmiany niepowiązanych komponentów.
- Duplikacja: znajdź powieloną logikę, odróżniając przypadkową duplikację od podobnych reguł, które powinny ewoluować niezależnie.
- Testy: zapisz, które ważne zachowania są objęte testami, które testy są wiarygodne i jakie zależności sprawiają, że test wymaga usług zewnętrznych.
- Eksploatacja i dostarczanie: odnotuj istotne awarie produkcyjne lub regresje, trudności z wdrożeniem zmiany oraz związane z nią kroki ręczne, jeśli dotyczą analizowanego obszaru.
Jeśli korzystasz z analizy statycznej, zachowaj nazwę narzędzia, reguły, wersję i polecenie. Sama liczba bez tych informacji nie jest odtwarzalna. Jeśli konfiguracja na to pozwala, oddziel też kod wygenerowany lub zewnętrzny i odnotuj wykluczenia.
Wybierz weryfikowalne wskaźniki i zapisz ich ograniczenia
Wybierz wskaźniki odpowiadające hipotezie. W przypadku refaktoryzacji mającej na celu odizolowanie logiki przydatne mogą być: liczba zależności potrzebnych do jej przetestowania, obecność odpowiednich testów zachowania oraz czas potrzebny osobie z zespołu na znalezienie miejsca wymagającego zmiany. Aby ograniczyć sprzężenie, można sprawdzić, ile komponentów trzeba zmodyfikować w reprezentatywnym zadaniu.
Nie traktuj czasu ani liczby jako uniwersalnej prawdy: wpływają na nie rozmiar zadania, doświadczenie osoby wykonującej pracę i przerwy. Jeśli korzystasz z takich danych, zapisz te warunki i traktuj wynik jako sygnał, a nie porównanie produktywności poszczególnych osób.
Opisz każdy wskaźnik za pomocą czterech informacji: co mierzy, jak jest uzyskiwany, jakiego wyniku oczekiwano i czego nie może dowieść. Na przykład liczba zależności może wykazać ich redukcję, ale nie dowodzi, że nowe abstrakcje są łatwe do zrozumienia. Powinna to zweryfikować recenzja techniczna.
Porównaj stan przed i po, stosując tę samą metodę
Po refaktoryzacji powtórz analizę dla tego samego zakresu i przy użyciu tej samej konfiguracji, w miarę możliwości w równoważnych warunkach. W przeglądzie oddziel zmiany funkcjonalne od strukturalnych. Jeśli oba rodzaje zmian wprowadzono jednocześnie, określ, które dowody dotyczą każdej z nich, i nie przypisuj całego wyniku refaktoryzacji.
Oprócz metryk przetestuj rzeczywistą lub reprezentatywną zmianę: popraw regułę, dodaj warunek biznesowy albo dostosuj integrację. Sprawdź, które pliki trzeba było zmodyfikować, jakie testy były potrzebne i gdzie pojawiły się wątpliwości. Nie trzeba tworzyć sztucznego zadania, jeśli istnieje już porównywalna praca; trzeba jednak unikać przedstawiania anegdotycznego wrażenia jako rozstrzygającego wyniku.
Spójna poprawa łączy różne sygnały: na przykład mniej zależności potrzebnych do testowania reguły, bardziej ukierunkowane testy i ścieżkę wprowadzania zmian, którą zespół potrafi wyjaśnić. Jeśli złożoność metody maleje, ale logika staje się bardziej rozproszona lub trudniej prześledzić przepływ, bilans wymaga ponownej oceny.
Połącz pomiary z przeglądem i opiniami zespołu
Przegląd techniczny powinien sprawdzić, czy odpowiedzialności są wyraźniej rozdzielone, nazwy odzwierciedlają domenę i nowe interfejsy odpowiadają na rzeczywistą potrzebę. Powinien też wykrywać wprowadzone ryzyka: zduplikowane kontrakty, niejasne odwrócenie zależności, przypadkowe zmiany zachowania albo nową warstwę, która jedynie przekazuje wywołania dalej.
Opinie zespołu dostarczają dowodów dotyczących zrozumiałości i eksploatacji. Zapytaj, czy łatwiej znaleźć regułę, napisać test lub oszacować zakres zmiany. Odnoś odpowiedzi do konkretnych przykładów i zapisuj rozbieżności: architektura może być jasna dla jej autora, a nieprzejrzysta dla osoby utrzymującej system.
W PHP sprawdź również, czy refaktoryzacja zachowuje istniejące kontrakty: typy, wyjątki, efekty uboczne, serializację i obserwowalne zachowanie API. Bardziej uporządkowany projekt wewnętrzny nie rekompensuje regresji funkcjonalnej ani nieprzewidzianej niekompatybilności.
Typowe błędy przy mierzeniu łatwości utrzymania
- Pogoń za pokryciem: zwiększenie procentu może prowadzić do dodawania powierzchownych testów. Oceń, czy testowane są zachowania i przypadki ryzyka, a nie tylko to, czy wykonywane są linie kodu.
- Nagradzanie mniejszej liczby linii: skrócenie kodu może ukrywać decyzje i utrudniać przegląd zmian. Rozmiar nie jest bezpośrednią miarą przejrzystości.
- Optymalizacja wyniku punktowego: dostosowanie kodu do narzędzia może pozostawić problem projektowy bez zmian. Sprawdź, co oznacza ta zmiana, i potwierdź jej wpływ na rzeczywistym zadaniu.
- Porównywanie różnych zakresów: uwzględnienie nowych plików, wykluczonego kodu lub zmienionych reguł unieważnia interpretację. Zachowaj stabilną metodę albo wyjaśnij różnice.
- Ignorowanie zachowania: refaktoryzacja powinna zachować oczekiwane zachowanie, chyba że zmiana funkcjonalna została osobno zdefiniowana i zweryfikowana.
Krótki szablon ułatwiający decyzję o dalszych działaniach
Na zakończenie oceny zapisz:
- Obszar i cel: którą część zrefaktoryzowano i jaką zdolność do wprowadzania zmian chciano poprawić.
- Pomiar bazowy i metoda: rewizję kodu, narzędzia, konfigurację, zakres i wykluczenia.
- Zaobserwowane sygnały: wyniki przed i po oraz ograniczenia każdego wskaźnika.
- Praktyczna weryfikacja: testy, przegląd techniczny i dowody uzyskane podczas reprezentatywnej zmiany.
- Pozostałe ryzyka: nieobjęte testami zachowania, odłożony dług techniczny i skutki operacyjne wymagające sprawdzenia.
- Decyzja: kontynuuj, jeśli hipoteza znajduje potwierdzenie, a ryzyko jest akceptowalne; wprowadź korekty, jeśli sygnały są niejednoznaczne lub pojawia się problem ze zrozumieniem; zatrzymaj się, jeśli koszt lub ryzyko przewyższa oczekiwaną korzyść.
Końcowe pytanie nie brzmi, czy kod uzyskał lepszy wynik punktowy, lecz czy zespół może modyfikować tę część z większą przejrzystością i kontrolą. Odtwarzalny pomiar bazowy, kilka uzupełniających się sygnałów i rzetelny przegląd pozwalają podjąć tę decyzję bez mylenia działań refaktoryzacyjnych z udowodnioną poprawą.
