Introducción
De todos es sabido que es fundamental producir un código correctamente documentado.
¿Qué conviene documentar dentro del código?. Fundamentalmente tres cosas:
| Tipo de documentación | Información | A quién va dirigida |
| La interfaz | Qué hace (no como lo hace) una función o un método de una clase. Qué parámetros hay que pasar. Qué devuelve. Ejemplo de uso. |
Esta información es útil para las personas que utilizan funciones o clases diseñadas por otros |
| La implementación | Dentro de una función, cómo se lleva a cabo cada paso. Por qué se utiliza esta variable y no aquella. Qué algoritmo se utiliza. Qué hacen los métodos privados de una clase. |
Esta información sólo interesa a las personas que necesiten depurar o actualizar el bloque de código. |
| La toma de decisiones | Por qué se ha implementado de una determinada forma y no de otra (p.e. por razones de rendimiento o por optimización de recursos, etc..). |
Esta información interesa tanto a nivel de implementación (desarrollador) como a nivel funcional (responsable de desarrollo). |
Normalmente la información sobre la implementación no necesita salir del código.
Por el contrario, la información de la interfaz conviene pasarla a un documento independiente del código fuente (manual de uso). La persona que necesite utilizar una determinada librería de clases o funciones tendrá toda la información necesaria: qué hace cada elemento y cómo se utiliza. No necesita acceder al código fuente.
El problema con este tipo de documentación es que cada vez que se modifica algo en el código (actualizaciones, corrección de errores, etc...) hay que reflejarlo también en el manual de uso... doble trabajo.
Lo ideal por tanto sería poder automatizar de alguna forma este proceso.
Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. Javadoc es la herramienta estándar en Java. Para PHP una de las herramientas más utilizadas es phpDocumentor (www.phpdoc.org).
El funcionamiento básico se representa en el siguiente esquema:
Usuarios que han visto este tema también han visto...
- Crear un log de errores en PHP
- Leer XML con SimpleXML de PHP
- Mostrar el signo zodiacal en PHP
- Ejecutar PHP en WordPress
- Funciones Relacionadas con el protocolo FTP
- Versión imprimible de este documento
- Enviar por e-mail este documento
Información legal | Política de Privacidad | Contacte con nosotros
Otro proyecto de Factoría de Internet. Copyright© 2003-2011 Factoría de Internet S.L.. Todos los derechos reservados.