Tengo una base de código privada bastante grande que ha evolucionado durante unos diez años. No estoy usando phpDocumentor, pero dado que el uso de secciones docblock se ha convertido en un estándar en proyectos de código abierto, también he adoptado escribir docblocks para todos los métodos públicos en mi repositorio. La mayoría de los bloques solo contienen una pequeña descripción y sugerencias para todos los parámetros y el tipo de retorno.
Con la llegada del análisis estático, estos tipos de letra me han ayudado mucho a encontrar inconsistencias y posibles errores. Últimamente he convertido toda la base de código (ahora ejecutándose en PHP7.2) para tener todos los parámetros y valores de retorno insinuados cuando sea posible, utilizando las sugerencias de tipo de PHP. Y ahora me pregunto ... ¿No son redundantes estos tipos de letra docblock? Se requiere bastante trabajo para mantener todos los bloques de documentos sincronizados con el código en constante cambio y, dado que no agregan ninguna información nueva, me pregunto si es mejor eliminarlos por completo o no.
Por un lado, eliminar la documentación se siente mal, incluso cuando es redundante. En el otro, tengo muchas ganas de romper con el principio de no insinuar el tipo de cosas cotidianas que ya está insinuado.
Respuestas:
La información que se puede encontrar en el código no debe duplicarse en los comentarios.
En el mejor de los casos, es un esfuerzo desperdiciado mantenerlos sincronizados. Lo más probable es que eventualmente se desincronicen. En ese punto, son simplemente confusos.
Si observa el equivalente de DocBlock en lenguajes estáticamente escritos (por ejemplo, Java, C #), encontrará que los comentarios de documentos no contienen información de tipo. En la medida en que este sea el caso en su código PHP, le recomiendo encarecidamente que haga lo mismo. Por supuesto, cuando no se pueden aplicar sugerencias de tipo, un comentario sigue siendo su mejor alternativa.
Esto no es relevante para PHP, pero la información de tipos duplicados puede tener sentido cuando el tipo se infiere implícitamente (por ejemplo, Haskell).
fuente
Sí, los docblocks se han vuelto redundantes con php 7.
La mayor parte del tiempo de codificación se dedica a la lectura, por lo que tener que leer lo mismo dos veces afecta su productividad. Además, hace que sea fácil perderse los comentarios realmente importantes.
Ya no escribo docblocks, excepto cuando quiero escribir una matriz de cierto tipo (por ejemplo,
@return int[]o@param SomeStatus[] $statusList) o cuando quiero agregar un comentario sobre el método, los parámetros o el valor de retorno. Me pareció importante deshabilitar la inspección de phpstorm que se dispara cuando no tienes todos los parámetros y los tipos de retorno en un docblock si tienes un docblock.fuente
El código y la documentación generalmente tienen audiencias diferentes: la documentación es para usuarios de esa función. No deberían tener que mirar el código para entender los tipos. Por lo tanto, la documentación debe incluir toda la información necesaria, incluidos los tipos.
En algunos sistemas, no es necesario especificar un tipo de parámetro en la documentación porque el tipo puede tomarse del código. PHPDoc no es tal sistema. En cambio, la
@parametiqueta está documentada queEl "bastante trabajo para mantener todos los bloques de documentos sincronizados con el código siempre cambiante" se reduce un poco porque PHPDoc verificará las sugerencias de tipo de documentación contra las sugerencias de tipo de código. Este es un tipo de análisis lineal / estático, por lo tanto, haga que su generación de documentación sea parte de su proceso de prueba automatizado.
Otra pregunta que es posible que desee hacerse es por qué estas funciones están documentadas en este detalle cuando están "siempre cambiando". La motivación habitual es crear un manual de referencia HTML de sus interfaces. Pero si la documentación nunca se lee fuera de un IDE, o si no tiene interfaces estables donde la documentación tiene sentido, entonces los bloques de documentos detallados son innecesarios o incluso engañosos. Puede ser mejor solo escribir un resumen y diferir documentos completos hasta que haya llegado a un diseño estable.
fuente