Question

Hola.

Estoy interesado en aprender la manera correcta de documentar código, y en especial PHP.
Utilizo PhpStorm como IDE para desarrollar el código y mirando un poco por internet veo que lo más utilizado es PhpDocumentor.

¿Alguien sabe si hay algún standard para la documentación de código y si este software lo cumple?

Un saludo y gracias por adelantado.

Answer 1

Parece que ninguno documentamos, al menos de esta forma... nosotros ponemos comentarios en el código, pautando con el cliente el idioma.

Los comentarios solo documentan desiciones de implementación (Ej: se usó una colección en vez de un vector para agregar métodos de agregación) o sutilezas técnicas (Ej:

// Maldita aproximación para evitar errores de redondeo en un decimal perdido por allá a lo lejos que hace que $totalPagar == $totalMedios no funcione cuando debería
   if($totalPagar - $totalMedios > 0.001) {
      ...

También notas que reflejan cambios o ajustes pedidos por el cliente sobre el código original (que ya funcionaba pero que no le gusta) para reflejar quién y cuándo se pidió la animalada :-)

A veces se pone un generoso comentario al principio de las clases para indicar qué son y relacionarlas con un Requerimiento Funcional, cosa que se justifica en proyectos grandes (de 70 a 100 clases para arriba en el Modelo), pero no hacemos nada que se parezca a la salida de un JavaDoc o similar.

Supongo que mucho de esto depende de quién será el destinatario de la documentación: yo rara vez documentamos para alguien distinto de "nosotros en el futuro".

Sin dudas de que hay que documentar, pero el tema tiene varios matices y no hay standard formal ni de facto para esto...

Saludos cordiales!