- \n
- Introduzione<\/a><\/li>\n\n\n\n
- Complessit\u00e0 del codice<\/a>\n
- \n
- Cyclomatic Complexity<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Refactoring<\/a>\n
- \n
- Come dare priorit\u00e0 ai file<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Cos’\u00e8 Churn PHP<\/a>\n
- \n
- Come funziona<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Le metriche<\/a>\n
- \n
- Times Changed<\/a><\/li>\n\n\n\n
- Complexity<\/a><\/li>\n\n\n\n
- Score<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Esempi pratici di refactoring<\/a>\n
- \n
- ItemController.php (Stato iniziale)<\/a><\/li>\n\n\n\n
- Passaggi per il refactoring<\/a><\/li>\n\n\n\n
- CreateController.php<\/a><\/li>\n\n\n\n
- GetListController.php<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Approfondimento su Churn PHP<\/a>\n
- \n
- Configurazione avanzata<\/a><\/li>\n\n\n\n
- File di esempio churn.yml<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Conclusione<\/a><\/li>\n<\/ol>\n\n\n\n
Introduzione<\/h2>\n\n\n\n
Quante volte, iniziando a lavorare per una nuova azienda, hai aperto un file contenente una sola classe e, con grande sorpresa, hai scoperto che contiene 3000 righe di codice? A me \u00e8 capitato tantissime volte. E mi chiedo sempre perch\u00e9 noi sviluppatori non dedichiamo del tempo a un’attivit\u00e0 fondamentale che, molto spesso, farebbe risparmiare tempo e soldi in futuro? Mi riferisco al refactoring.<\/p>\n\n\n\n
In molti mi hanno detto: “Finch\u00e9 funziona, non si tocca”. Oppure: “Sono solo dettagli”, o ancora la classica scusa: “Non abbiamo tempo”. Ma il tempo per altre attivit\u00e1, come un meme o una sigaretta, spesso lo troviamo in molti. \u00c8 vero, toccare un pezzo di codice implica uno sforzo ulteriore: altri test (automatici o manuali), altri messaggi di commit a cui pensare, insomma, altre grane. Ma siamo sviluppatori, non lavoriamo in un fast food – spoiler: io ho lavorato in un fast food quando ero giovane<\/em>.<\/p>\n\n\n\n
Per quanto mi riguarda, ridurre la complessit\u00e0 nel codice \u00e8 e deve essere una priorit\u00e0<\/strong>. Il refactoring \u00e8 un’attivit\u00e0 di sviluppo esattamente come lo sono scrivere test, fare bug fixing o sviluppare nuove funzionalit\u00e0.<\/p>\n\n\n\n
Complessit\u00e0 del codice<\/h2>\n\n\n\n
Il problema di una classe contenente 3000 linee non \u00e8 la lunghezza, ma la complessit\u00e0 nel leggere un “mostro” del genere. Avere molte ramificazioni significa dover tenere traccia di un numero troppo alto di variabili e flussi. Questo sforzo \u00e8 semplicemente troppo dispendioso in termini di sforzo mentale, e ci\u00f2 porta a errori. Inoltre, un “mostro” di 3000 righe sar\u00e0 difficile da testare nella sua interezza, perch\u00e9 ci saranno sicuramente dipendenze ed eccezioni di cui tenere conto.<\/p>\n\n\n\n
Ma come si misura la complessit\u00e0 del codice? Un punto di partenza \u00e8 la Cyclomatic complexity<\/a>, ovvero una metrica software utilizzata per indicare una misura quantitativa del numero di percorsi linearmente indipendenti attraverso il codice sorgente di un programma<\/em>. \u00c8 stata sviluppata da Thomas J. McCabe, Sr.<\/em> nel 1976. In altre parole, la Cyclomatic Complexity indica quante decisioni (if, loop, switch, ecc.) ci sono nel codice, aiutando a valutare la sua manutenibilit\u00e0 e il numero minimo di test necessari. Pi\u00f9 \u00e8 alta, pi\u00f9 il codice \u00e8 complesso da capire e testare. Ed ecco perch\u00e9 l’elevata complessit\u00e0 del codice \u00e8 (quasi) sempre negativa. Scrivo quasi<\/em> perch\u00e9, se una classe non viene quasi mai toccata, potrebbe non risultare un grosso problema.<\/p>\n\n\n\n
Refactoring<\/h2>\n\n\n\n
Come dicevo all’inizio dell’articolo, ho personalmente lavorato in molte aziende in cui la complessit\u00e0 del codice non era neanche percepita come un problema, e sto parlando di aziende sia italiane che straniere, grandi e piccole. E non \u00e8 vero che solo i progetti legacy soffrono di questo problema; a volte \u00e8 proprio il progetto in corso che, per poca sensibilit\u00e0 da parte degli sviluppatori \u2013 e dei manager \u2013 si porta dietro questo macigno, aggiungendo, giorno dopo giorno, complessit\u00e0 su complessit\u00e0. Un giorno sar\u00e0 chiamato “legacy”, e i futuri sviluppatori diranno che \u00e8 troppo complesso.<\/p>\n\n\n\n
Allocare un intero sprint per un vasto refactoring non \u00e8 mai la soluzione, ma fare in modo che il refactoring diventi parte della nostra pratica quotidiana dovrebbe essere la strada giusta da seguire. Se facciamo refactoring mentre apportiamo modifiche al nostro codice, finiamo per lavorare con un codice progressivamente migliore. Ma come? A quali file dare la priorit\u00e0? Una regola \u00e8 dare priorit\u00e0 ai file che hanno un alto grado di complessit\u00e0 e cambiano abbastanza frequentemente<\/strong>.<\/p>\n\n\n\n
\u00c8 proprio la combinazione tra complessit\u00e0 e modifiche frequenti che guider\u00e0 il nostro refactoring.<\/p>\n\n\n\n
Cos’\u00e9 Churn PHP<\/h2>\n\n\n\n
Churn PHP aiuta a scoprire buoni candidati per il refactoring. Michael Feathers<\/a> ha coniato il termine “churn” per descrivere il tasso di modifiche apportate ai file di un progetto. Il churn pu\u00f2 essere quantificato con un valore, simile a quello utilizzato per misurare la complessit\u00e0 del codice. Supponendo che ogni classe sia definita in un file separato e che ogni modifica a una classe corrisponda a un nuovo commit nel sistema di controllo versione, un metodo pratico per misurare il churn di una classe consiste nel conteggiare i commit che interessano il file in cui \u00e8 contenuta.<\/p>\n\n\n\n
\u00c9 proprio su questa combinazione di fattori, complessit\u00e1 e churn di una classe<\/em>, che Churn PHP fornisce dei valori numerici per individuare facilmente le classi che devono essere modificate spesso, ma che sono anche molto difficili da modificare, perch\u00e9 hanno un’elevata complessit\u00e0 del codice. <\/p>\n\n\n
\n![\"image](\"https:\/\/github.com\/bmitch\/churn-php\/raw\/master\/img\/output.png\")
Esempio di analisi Churn PHP<\/figcaption><\/figure>\n<\/div>\n\n\n Le metriche<\/h2>\n\n\n\n
- \n
Times Changed<\/strong>: Si riferisce al numero di volte in cui un determinato file o classe \u00e8 stato modificato in un dato periodo. \u00c8 un semplice conteggio dei commit relativi a quel file. In un progetto PHP, un numero elevato di modifiche a una classe o funzione specifica potrebbe indicare aree del codice che vengono aggiornate frequentemente, il che potrebbe suggerire una potenziale instabilit\u00e0 o requisiti in evoluzione.<\/p><\/li>\n\n\n\n
Complexity<\/strong>: La complexity si riferisce a quanto il codice in una determinata classe o file sia complesso. Questo pu\u00f2 includere fattori come il numero di funzioni\/metodi, le dichiarazioni condizionali, i cicli annidati e la struttura generale del codice. Un file o una classe pi\u00f9 complessa pu\u00f2 risultare pi\u00f9 difficile da mantenere, comprendere e modificare, il che potrebbe portare a un churn pi\u00f9 elevato. La complessit\u00e0 \u00e8 spesso misurata utilizzando strumenti come la Cyclomatic complexity, che valuta il numero di percorsi indipendenti nel codice.<\/p><\/li>\n\n\n\n
Score<\/strong>: Lo score \u00e8 una metrica complessiva che combina sia il Times Changed che la Complexity. \u00c8 un modo per quantificare quanta attenzione potrebbe richiedere un determinato file o classe. Un punteggio pi\u00f9 alto indica che il file ha subito molte modifiche e potrebbe anche avere una complessit\u00e0 elevata, suggerendo che si tratti di una parte critica o instabile del codice. Questo potrebbe indicare aree che necessitano di refactoring, test aggiuntivi o una migliore documentazione per garantirne la manutenibilit\u00e0 a lungo termine.<\/p><\/li>\n<\/ol>\n\n\n\n
Un valore di churn alto combinato con una complessit\u00e0 elevata potrebbe indicare aree del codice difficili da mantenere o soggette a bug, orientando le decisioni riguardo al refactoring o alla semplificazione del codice.<\/p>\n\n\n\n
Esempi pratici di refactoring<\/h2>\n\n\n\n
Troppa teoria potrebbe mascherare l’impatto che queste metriche hanno sul nostro lavoro. Voglio mostrare un esempio concreto di come si pu\u00f2 semplificare una classe per rendere l’articolo pi\u00f9 pratico e applicabile. \u00c9 un esempio molto semplice, ma ci sono casi pi\u00fa complessi come quelli di classi interdipendenti, in cui bisogna rompere le dipendenze introducendo nuovi design patterns.<\/p>\n\n\n\n
Di seguito, la classe ItemController.php<\/em>, contenuta in un progetto Laravel.<\/p>\n\n\n\n
<?php\n\n\/* NOTE: here namespace and use *\/\n\nclass ItemController extends Controller\n{\n \/**\n * @param Request $request\n * @return JsonResponse\n *\/\n public function create(Request $request): JsonResponse\n {\n $validate_data = $request->validate([\n 'slug' => 'required|string',\n 'item' => 'required|string',\n 'session_id' => 'nullable|string',\n ]);\n\n \/\/ Find message\/letter for its slug\n $message = Message::where('slug', \"like\", \"%\" . $validate_data['slug'] . \"%\")->first();\n\n if (!$message) {\n return response()->json([\n 'item' => '',\n 'session_id' => '',\n 'slug' => '',\n 'error' => 'No message found!'\n ]);\n }\n\n \/\/ Is there already an items for this user?\n $item = null;\n if (isset($validate_data['session_id'])) {\n $item = Item::where('session_id', $validate_data['session_id'])->where('message_id', $message->id)->first();\n }\n\n if ($item) {\n Item::destroy($item->id);\n }\n\n if ($validate_data['item'] === '' \n || $validate_data['item'] === Constants::LINK) {\n return response()->json([\n 'item' => '',\n 'session_id' => '',\n 'slug' => '',\n 'error' => 'No item selected!'\n ]);\n }\n\n \/\/ Save new items\n $item = new Item();\n $item->message_id = $message->id;\n $item->user_id = (Auth::check()) ? Auth::user()->id : Constants::NOT_LOGGED_USER_ID;\n $item->name = $validate_data['name'];\n $item->session_id = (isset($validate_data['session_id'])) ? $validate_data['session_id'] : \\Session::getId();\n $item->save();\n\n return response()->json([\n 'item' => $item->item,\n 'session_id' => $item->session_id,\n 'slug' => $validate_data['slug'],\n ]);\n }\n\n \/**\n * @param Request $request\n * @return JsonResponse\n *\/\n public function getPublicItems(Request $request)\n {\n $request->merge(['slug' => $request->slug]);\n\n $validate_data = $request->validate([\n 'slugs' => 'required|string',\n ]);\n\n \/\/ get messages from slugs\n $arrSlugs = json_decode($validate_data['slugs'], true);\n $query = Message::query();\n foreach ($arrSlugs as $slug) {\n $query->orWhere('slug', \"like\", \"%-\" . $slug);\n }\n $messages = $query->get(['id', 'slug']);\n\n $ids = array();\n foreach ($messages as $message) {\n $ids[] = $message->id;\n }\n\n \/\/ get items by messages ids\n $items = Item::select('item', 'message_id', \\DB::raw('count(item) as item_count'))\n ->whereIn('message_id', $ids)\n ->groupBy('item', 'message_id')\n ->orderBy('message_id', 'desc')\n ->orderBy('item', 'desc')\n ->get();\n\n \/\/ Prepare result\n $results = [];\n foreach ($items as $item) {\n foreach ($messages as $message) {\n if ($item->message_id == $message->id) {\n $result = array();\n $result['slug'] = $this->getPublicSlug($message->slug);\n $result['item'] = $item->item;\n $result['count'] = $item->item_count;\n\n $results[] = $result;\n }\n }\n }\n\n return response()->json([\n 'items' => $results,\n ]);\n }\n}\n<\/code><\/pre>\n\n\n\nNello specifico questa classe \u00e9 un controller nella directory Http\/Controllers<\/em> di base, e che Churn PHP mi indica con questi valori:<\/p>\n\n\n\n
+---------------------------------------------------+---------------+------------+-------+\n| File | Times Changed | Complexity | Score |\n+---------------------------------------------------+---------------+------------+-------+\n| app\/Http\/Controllers\/ItemController.php | 14 | 17 | 0.102 |\n+---------------------------------------------------+---------------+------------+-------+\n<\/code><\/pre>\n\n\n\nIn effetti \u00e9 una classe che ho cambiato spesso, e che contiene vari metodi pubblici, quindi possiamo dire che contiene molte responsabilit\u00e1 e che viola l’SRP<\/em> (Single Responsibility Principle<\/a><\/em>). <\/p>\n\n\n\n
Ecco gli steps che ho seguito per semplificare la classe:<\/p>\n\n\n\n
- \n
- Dove mancano, ho creato nuove classi di Request, in questa maniera inizio con lo spostare la logica delle validazioni dal controller alle classi Requests;<\/li>\n\n\n\n
- Dove posso, incapsulo alcune logiche in metodi privati, in maniera da eliminare commenti rindondanti e semplificare la lettura del codice. Non c’\u00e9 nessuno motivo di mantenere un commento di questo tipo
\/\/ Get messages by slugs<\/code> quando con PHPStorm posso comodamente selezionare il pezzo di codice interessato, e con un semplice comando come Extract Method<\/a>, posso generare un nuovo metodo che semplicemente chiamer\u00f3getMessagesBySlugs<\/code>; il codice ora \u00e9 diventato autoesplicativo. In pi\u00fa posso eliminare alcune variabili perch\u00e9 ora sfrutto il ritorno inline dei valori nei nuovi metodi;<\/li>\n\n\n\n- User\u00f3 i metodi pubblici di questa classe per creare nuove classi, separate, che hanno una singola responsabilit\u00e0. I nomi delle nuove classi rispecchiano ora le funzionalit\u00e1, che non saranno pi\u00fa affogate in una grande classe generale. Piccolo dettaglio: le nuove classi avranno un unico metodo pubblico invoke() e saranno contenute nella cartella
Item<\/code>. Devo tenere conto di questa cosa anche nei namespaces<\/em> e nel file delle rotte, dove scriver\u00f3 direttamente il namespace della classe che mi serve invece di indiciare i nomi dei metodi;<\/li>\n\n\n\n- Se posso, far\u00f3 anche leva su una tecnica chiamata Return Early Pattern<\/em>, ovvero si scrive il ritorno di una funzione o di un metodo non appena una certa condizione non \u00e8 soddisfatta, invece di permettere al codice di continuare l’esecuzione, o invece di circordare un blocco di codice se una condizione \u00e9 rispettata.<\/li>\n<\/ol>\n\n\n\n
Qui di seguito, le nuove classi.<\/p>\n\n\n\n
CreateController.php<\/h3>\n\n\n\n
<?php\n\n\/* NOTE: here namespace and use *\/\n\nclass CreateController extends Controller\n{\n \/**\n * @param ItemCreateRequest $request\n * @return JsonResponse\n *\/\n public function __invoke(ItemCreateRequest $request): JsonResponse\n {\n $validateData = $request->validated();\n\n if ($validateData['item'] === ''\n || $validateData['item'] === Constants::LINK) {\n\n return response()->json([\n 'item' => '',\n 'session_id' => '',\n 'slug' => '',\n 'error' => 'No item selected!',\n ]);\n }\n\n $message = Message::where('slug', 'like', '%' . $validateData['slug'] . '%')\n ->first();\n\n if (!$message) {\n return response()->json([\n 'item' => '',\n 'session_id' => '',\n 'slug' => '',\n 'error' => 'No message found!',\n ]);\n }\n\n if ($sessionId) {\n $this->deleteItemForUserIfExists($validateData['session_id'] ?? null, $message->id);\n }\n \n $item = $this->storeNewItem($message->id, $validateData);\n \n return response()->json([\n 'item' => $item->item,\n 'session_id' => $item->session_id,\n 'slug' => $validateData['slug'],\n ]);\n }\n\n \/**\n * @param string $sessionId\n * @param int $messageId\n *\n * @return void\n *\/\n private function deleteItemForUserIfExists(string $sessionId, int $messageId): void\n {\n \n $item = Item::where('session_id', $sessionId)\n ->where('message_id', $messageId)\n ->first();\n\n if ($item) {\n $item->delete();\n }\n }\n\n \/**\n * @param int $message\n * @param array $validateData\n *\n * @return Item\n *\/\n private function storeNewItem(int $messageId, array $validateData): Item\n {\n $item = new Item();\n $item->message_id = $messageId;\n $item->user_id = (Auth::check())\n ? Auth::user()->id\n : Constants::NOT_LOGGED_USER_ID;\n $item->name = $validateData['name'];\n $item->session_id = (isset($validateData['session_id']))\n ? $validateData['session_id']\n : \\Session::getId();\n $item->save();\n\n return $item;\n }\n}\n<\/code><\/pre>\n\n\n\nGetListController.php<\/h3>\n\n\n\n
<?php\n\n\/* NOTE: here namespace and use *\/\n\nclass GetListController extends Controller\n{\n \/**\n * @param GetItmesListRequest $request $request\n * @return JsonResponse\n *\/\n public function __invoke(GetItmesListRequest $request): JsonResponse\n {\n $validateData = $request->validated();\n\n $messages = $this->getMessagesBySlugs($validateData['slugs']);\n\n $ids = [];\n foreach ($messages as $message) {\n $ids[] = $message->id;\n }\n\n \/\/ get items by messages ids\n $items = Item::select('item', 'message_id', \\DB::raw('count(item) as item_count'))\n ->whereIn('message_id', $ids)\n ->groupBy('item', 'message_id')\n ->orderBy('message_id', 'desc')\n ->orderBy('item', 'desc')\n ->get();\n\n $results = $this->prepareResults($items, $messages);\n\n return response()->json([\n 'items' => $results,\n ]);\n }\n\n \/**\n * @param string $slugs\n * @return Builder[]|Collection\n *\/\n private function getMessagesBySlugs(string $slugs): array|Collection\n {\n $arrSlugs = json_decode($slugs, true);\n\n $query = Message::query();\n foreach ($arrSlugs as $slug) {\n $query->orWhere('slug', 'like', '%-' . $slug);\n }\n\n return $query->get(['id', 'slug']);\n }\n\n \/**\n * @param array|Collection $items\n * @param array|Collection $messages\n * \n * @return array\n *\/\n private function prepareResults(array|Collection $items, array|Collection $messages): array\n {\n $results = [];\n foreach ($items as $item) {\n foreach ($messages as $message) {\n if ($item->message_id == $message->id) {\n $results[] = [\n 'slug' => $this->getPublicSlug($message->slug),\n 'item' => $item->item,\n 'count' => $item->item_count,\n ];\n }\n }\n }\n\n return $results;\n }\n}\n<\/code><\/pre>\n\n\n\nCon ulteriori ottimizzazioni, come l’introduzione di una classe di servizio da iniettare nel costruttore della classe, e una gestione pi\u00f9 strutturata delle eccezioni, si potrebbe rendere il codice ancora pi\u00f9 robusto e riutilizzabile.<\/p>\n\n\n\n
Approfondimento su Churn PHP<\/h2>\n\n\n\n
Churn PHP \u00e8 uno strumento potente, ma spesso viene utilizzato con configurazioni di base che non sfruttano appieno il suo potenziale. Personalizzare il file churn.yml<\/em> consente di adattare l\u2019analisi alle specifiche esigenze di un progetto. Ad esempio, si possono escludere file o directory non rilevanti come vendor\/<\/em> o storage\/<\/em>, oppure impostare soglie personalizzate per complessit\u00e0 e churn, evidenziando solo i file realmente critici. Di seguito un piccolo esempio di file di configurazione churn.yml<\/em>:<\/p>\n\n\n\n
# This list is used only if there is no argument when running churn.\n# Default: <empty>\ndirectoriesToScan:\n - src\n - tests\/\n\n# Files to ignore when processing. The full path to the file relative to the root of your project is required.\n# Also supports regular expressions.\n# Default: All PHP files in the path provided to churn-php are processed.\nfilesToIgnore:\n - vendor\/*\n - storage\/*\n\n# The command returns an 1 exit code if the highest score is greater than the threshold.\n# Disabled if null.\n# Default: null\nmaxScoreThreshold: 0.9\n<\/code><\/pre>\n\n\n\nInoltre, Churn PHP supporta diversi formati di output, come JSON, ideali per integrazioni avanzate con dashboard o pipeline CI\/CD. Configurare il tool in modo da eseguire analisi incrementali direttamente su GitHub Actions o GitLab CI, ad esempio, permette di identificare i file problematici in tempo reale, prima che il codice venga integrato. Una configurazione curata trasforma Churn PHP in un alleato imprescindibile per mantenere la qualit\u00e0 del codice alta senza rallentare lo sviluppo.<\/p>\n\n\n\n
Per quanto riguarda l’installazione, la compatibilit\u00e1 e ulteriori configurazioni, fare riferimento al repository Github Churn PHP<\/a>.<\/p>\n\n\n\n
Rector e Churn PHP: due strumenti complementari per il refactoring<\/h2>\n\n\n\n
Un’ultima nota riguardo ad un altro potente strumento utilizzato per il refactoring: Rector<\/strong>.<\/p>\n\n\n\n
Rector \u00e8 uno strumento di automatic refactoring<\/em> per PHP che permette di trasformare il codice sorgente in maniera programmata e automatizzata, applicando regole predefinite o personalizzate. A differenza di Churn PHP, che si concentra sull’analisi del codice per individuare le classi con un alto tasso di modifiche (churn) e complessit\u00e0, Rector interviene direttamente sul codice, eseguendo il refactoring in modo rapido e sicuro.<\/p>\n\n\n\n
L\u2019uso combinato di questi strumenti \u00e8 estremamente efficace: Churn PHP aiuta a identificare i file che necessitano di interventi prioritari grazie a metriche concrete, mentre Rector pu\u00f2 automatizzare molte delle modifiche necessarie, come la rimozione di codice ridondante, l\u2019adeguamento a standard moderni o la semplificazione di pattern complessi, basandosi su regole impostate dagli sviluppatori. Questa sinergia consente di ottimizzare il refactoring, bilanciando analisi intelligente e automazione, per ottenere un codice pi\u00f9 pulito e manutenibile senza rallentare il flusso di sviluppo.<\/p>\n\n\n\n
Per l’installazione e la documentazione, fare riferimento al repository Github di Rector<\/a>.<\/p>\n\n\n\n
Conclusioni<\/h2>\n\n\n\n
- User\u00f3 i metodi pubblici di questa classe per creare nuove classi, separate, che hanno una singola responsabilit\u00e0. I nomi delle nuove classi rispecchiano ora le funzionalit\u00e1, che non saranno pi\u00fa affogate in una grande classe generale. Piccolo dettaglio: le nuove classi avranno un unico metodo pubblico invoke() e saranno contenute nella cartella
- File di esempio churn.yml<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Passaggi per il refactoring<\/a><\/li>\n\n\n\n
- Complexity<\/a><\/li>\n\n\n\n
- Le metriche<\/a>\n
- Cos’\u00e8 Churn PHP<\/a>\n
- Refactoring<\/a>\n
- Complessit\u00e0 del codice<\/a>\n