¿La verbosidad de PHPDoc es más problemática de lo que vale? [cerrado]

Question

Intenté usar PHPDoc por primera vez hoy y rápidamente me encontré con un problema.

Por cada 1 línea de declaraciones de variables, tenía al menos 5 líneas de comentarios. Ejemplo:

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

Por supuesto, los beneficios son buenos, pero esto convierte un archivo de configuración de 10 líneas en un archivo de 60 líneas. Me lleva una eternidad completar, y aún no estoy convencido de que agregue mucho sobre una simple frase.

También arroja un nudo en mi flujo de trabajo. Todo está bien y bien hasta que necesite hacer cambios radicales. Con mis bien documentados bloques de documentos, de repente ya no tengo que refactorizar mi código, pero necesito volver a escribir todos estos detalles tediosos. Espera hasta el final que dices? HAH! Entonces la documentación nunca sucederá.

Además de todo esto, me obliga a usar el estilo C / ** / comentarios en el medio de mi código. Esto me vuelve loco durante el desarrollo, ya que elimina la capacidad de comentar grandes bloques a pedido. Ahora para comentar un gran bloque de código, necesito extraer algo como: rango, s / ^ / # /; luego deshacerlo más tarde. Molesto!

En pocas palabras: me gusta PHPDoc, me encanta el código bien documentado, ¡pero 5 líneas de comentarios por cada línea de código es demasiado! . ¿Hay características que me faltan? ¿Es este un problema común?

Answer 1

Que sea o no exagerado depende en gran medida del uso previsto de su aplicación. Si está escribiendo una aplicación que solo será utilizada por una sola empresa o grupo, probablemente no necesite documentación exhaustiva de cada variable.

Por ejemplo, en este momento estoy trabajando en un proyecto con una base de código bastante extensa pero muy pocos desarrolladores (por ahora, solo yo). Estoy agregando bloques PHPDoc para dos cosas: clases y métodos. Para todo lo demás, comento con frecuencia, pero no en formato detallado de PHPDoc. La mayor parte de este código solo será visto por tres o cuatro personas, y la información que necesitarán es información de recuadro negro: qué envío a este método, qué espero obtener de él. Quieren saber cómo obtener datos de un Modelo, no para qué sirve una variable de clase privada.

Si estuviera escribiendo una aplicación que pretendía distribuir a otros desarrolladores o empresas, y esperaba que integraran mi aplicación con otros sistemas o ampliaran su funcionalidad, le daría más valor al uso más extenso de PHPDoc. Ese tipo de detalle definitivamente podría ser útil durante el mantenimiento a largo plazo.

Ejemplo: mi proyecto actual requerirá en algún momento la creación de una API para acceder desde otros sitios. Puede apostar que la API tendrá más comentarios y documentación escrita que líneas de código.