I tipi di docblock sono ridondanti quando si utilizza una digitazione rigorosa

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

Al massimo, è uno sforzo inutile per mantenerli sincronizzati. Più probabilmente, alla fine saranno fuori sincrono. A quel punto, sono solo confusi.

Se si osserva l'equivalente di DocBlock in lingue tipizzate staticamente (ad es. Java, C #), i commenti del doc non contengono informazioni sul tipo. Nella misura in cui questo è il caso nel tuo codice PHP, ti consiglio vivamente di seguire l'esempio. Ovviamente, quando non è possibile applicare il suggerimento sul tipo, un commento è ancora la tua migliore alternativa.

Questo non è rilevante per PHP, ma le informazioni sul tipo duplicato possono avere senso quando il tipo è implicitamente dedotto (ad esempio Haskell).

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

In alcuni sistemi, non è necessario specificare un tipo di parametro nella documentazione perché il tipo può essere preso dal codice. PHPDoc non è un sistema del genere. Invece, il tag @param è documentato che

When provided it MUST contain a Type to indicate what is expected

Il "un bel po 'di lavoro per mantenere tutti i docblock sincronizzati con il codice in continua evoluzione" è in qualche modo ridotto perché PHPDoc controllerà i suggerimenti sul tipo di documentazione con i suggerimenti sul tipo di codice. Questo è un tipo di analisi linting / statica, quindi rendi la tua generazione di documentazione parte della tua pipeline di test automatizzata.

Un'altra domanda che potresti chiederti è perché queste funzioni sono documentate in questo dettaglio quando "cambiano". La solita motivazione è creare un manuale di riferimento HTML delle tue interfacce. Ma se la documentazione non viene mai letta all'esterno di un IDE o se non si dispone di interfacce stabili in cui la documentazione ha senso, i docblock dettagliati non sono necessari o addirittura fuorvianti. Può essere meglio scrivere solo un sommario e posticipare i documenti completi fino a quando non sei arrivato a un design stabile.

Sì, i docblock sono diventati ridondanti con php 7.

La maggior parte del tempo nella lettura del codice viene speso, quindi dover leggere la stessa cosa influisce due volte sulla produttività. Inoltre, rende facile non notare commenti davvero importanti.

Non scrivo più docblocks, tranne quando voglio suggerire 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 attiva quando non hai i parametri e restituisci i tipi in un docblock se hai un docblock.