I suggerimenti di tipo docblock sono ridondanti quando si utilizza la digitazione rigorosa

Ho una base di codice privata abbastanza grande che si è evoluta per circa dieci anni. Non sto usando phpDocumentor ma dato che l'uso delle sezioni docblock è diventato piuttosto lo standard nei progetti open source, ho adottato la scrittura di docblock per tutti i metodi pubblici nel mio repository. La maggior parte dei blocchi contiene solo una piccola descrizione e suggerimenti per tutti i parametri e il tipo restituito.

Con l'arrivo dell'analisi statica, questi suggerimenti mi hanno aiutato molto a trovare incoerenze e possibili bug. Ultimamente ho convertito l'intera base di codice (ora in esecuzione su PHP7.2) per avere tutti i parametri e i valori di ritorno suggeriti dal tipo, ove possibile, usando i suggerimenti di PHP. E ora mi chiedo ... Questi suggerimenti per il blocco dei documenti non sono ridondanti? Richiede un bel po 'di lavoro per mantenere tutti i blocchi di documenti sincronizzati con il codice in continua evoluzione e poiché non aggiungono nuove informazioni, mi chiedo se sia meglio rimuoverli completamente o meno.

In una mano, la rimozione della documentazione risulta negativa, anche quando è ridondante. Nell'altro, ho davvero voglia di infrangere il principio del non-ripetizione-te stesso del principio quotidiano che è già stato suggerito.

Le informazioni che possono essere trovate nel codice non devono essere duplicate nei commenti.

Nel migliore dei casi, è uno sforzo sprecato per mantenerli sincronizzati. Più probabilmente alla fine usciranno fuori sincrono. A quel punto, sono solo confusi.

Se guardi l'equivalente di DocBlock in linguaggi tipicamente statici (ad es. Java, C #), scoprirai che i commenti dei documenti non contengono informazioni sul tipo. Nella misura in cui questo è il caso nel tuo codice PHP, ti consiglio vivamente di seguirne l'esempio. Ovviamente, laddove non è possibile applicare il suggerimento per tipo, un commento è comunque la migliore alternativa.

Questo non è rilevante per PHP, ma informazioni di tipo duplicate possono avere senso quando il tipo viene dedotto implicitamente (ad es. Haskell).

Sì, i blocchi di documenti sono diventati ridondanti con php 7.

La maggior parte del tempo dedicato alla programmazione è trascorsa a leggere, quindi dover leggere la stessa cosa due volte influisce sulla produttività. Inoltre, rende facile perdere commenti realmente importanti.

Non scrivo più docblock, tranne quando voglio digitare un array di un certo tipo (es. @return int[]O @param SomeStatus[] $statusList) o quando voglio aggiungere un commento sul metodo, i parametri o il valore di ritorno. Ho trovato importante disabilitare l'ispezione phpstorm che si innesca quando non hai tutti i parametri e restituisci i tipi in un blocco documenti se hai un blocco documenti.

Il codice e la documentazione in genere hanno un pubblico diverso: la documentazione è destinata agli utenti di quella funzione. Non dovrebbero guardare il codice per capire i tipi. Pertanto, la documentazione dovrebbe includere tutte le informazioni necessarie, compresi i tipi.

In alcuni sistemi, non è necessario specificare un tipo di parametro nella documentazione poiché il tipo può essere preso dal codice. PHPDoc non è un tale sistema. Invece, il @paramtag è documentato che

Se fornito, DEVE contenere un Tipo per indicare ciò che è previsto

Il "bel po 'di lavoro per mantenere sincronizzati tutti i blocchi di documenti con il codice in continua evoluzione" è in qualche modo ridotto perché PHPDoc controllerà i suggerimenti sul tipo di documentazione rispetto ai suggerimenti sul tipo di codice. Si tratta di una sorta di analisi di lanugine / statica, quindi fai in modo che la tua generazione di documentazione faccia parte della tua pipeline di test automatizzata.

Un'altra domanda che potresti porti è perché queste funzioni sono documentate in questo dettaglio quando "cambiano continuamente". La solita motivazione è quella di creare un manuale di riferimento HTML delle tue interfacce. Ma se la documentazione non viene mai letta al di fuori di un IDE, o se non si dispone di interfacce stabili in cui la documentazione ha un senso, i blocchi di documenti dettagliati non sono necessari o addirittura fuorvianti. Può essere meglio solo scrivere un riepilogo e rinviare i documenti completi fino a quando non si è arrivati ​​a un progetto stabile.