¿La mejor manera de documentar el código AJAX + PHP?

Question

Siempre he sido para documentar código, pero cuando se trata de AJAX + PHP, no siempre es fácil: ¡el código está muy extendido! La lógica, los datos, la presentación, lo que quieras, están divididos y mezclados entre el código del lado del servidor y el del lado del cliente. A veces también hay un código en el lado de la base de datos (procedimientos almacenados, vistas, etc.) que hace parte del trabajo.

Esto me desafía a encontrar una forma eficiente de documentar dicho código. Normalmente proporciono una lista de archivos .js dentro del archivo .php, así como una lista de archivos .php dentro del archivo .js. También hago comentarios en línea y descripciones de funciones, donde enumero qué función se usa según qué archivo y qué salida se espera. Hago tareas similares para los procedimientos de la base de datos. Tal vez hay un mejor método?

¿Alguna idea o experiencia?

Nota: esta pregunta se aplica a cualquier aplicación cliente + servidor, no solo Javascript + PHP.

Answer 1

Creo que es mejor tener un enfoque jerárquico.

Para la documentación de nivel API como en el nivel de función y de clase, escribir documentación en línea en el código HTML y generar la documentación fuera de ellos usando las muchas herramientas de documentación por ahí (JSDoc, phpDocumentor, OraDoclet, etc). Puntos de bonificación si sus herramientas de documentación pueden integrarse con sus herramientas de control de origen para que pueda saltar a líneas de código específicas de sus documentos de API.

Una vez que tenga las herramientas de doc en su lugar, comience a generar la documentación como parte de su proceso de compilación (tiene un proceso de compilación, ¿no?) Para cada compilación nueva y envíe la documentación a una ubicación web estándar.

Una vez que estos documentos api están en línea, puede crear una wiki para documentación de alto nivel, como navegador-> web-> interacciones db, historias de usuario, diagramas de esquema, etc. Lo mejor es escribir en breve prosa o viñetas para documentación de alto nivel, enlace a api docs y control de fuente cuando sea necesario.

Answer 2

Creo que su método es bastante bueno. Lo único es que todo lo que está dentro del archivo js es legible por otros y, por lo tanto, documentar qué archivos PHP se usan podría generar un agujero de seguridad, en el caso de que puedan acceder a un archivo que devuelve algo que no debería. Además, aunque no es un gran problema, en sitios de mayor tráfico, la descarga dice que 500 bytes de comentarios pueden sumarse.

Ambos no son grandes, solo son pensamientos que he tenido antes.

Answer 3

Sirva su javascript (y css) a través de PHP: puede mantener sus archivos fuente juntos para una fácil referencia cruzada y con un uso cuidadoso de los encabezados puede manejar fácilmente el almacenamiento en caché. Hacer esto también le permite tener una versión de fuente con mucho formato y comentarios pesados ​​que luego puede condensar u ocultar antes de enviarla al navegador.

function OutputJs($Content) { 
    ob_start(); 
    echo $Content; 
    $expires = DAY_IN_S; 
    header("Content-type: x-javascript"); 
    header('Content-Length: ' . ob_get_length()); 
    header('Cache-Control: max-age='.$expires.', must-revalidate'); 
    header('Pragma: public'); 
    header('Expires: '. gmdate('D, d M Y H:i:s', time()+$expires).'GMT'); 
    ob_end_flush(); 
} 

Answer 4

Para proyectos con una gran cantidad de Javascript, que utilizan un sistema de construcción (archivos make) con un javascript minimizer. Como señala el autor de jsmin, la eliminación de comentarios "fomenta un estilo de programación más expresivo porque elimina el costo de descarga de la auto-documentación limpia y letrada".

La ventaja es que jsmin también quita los comentarios de CSS, por lo que puede comenzar a comentar libremente allí también. (Creo que el uso de clases CSS es crucial para escribir JavaScript claro.)

Es una idea interesante utilizar PHP para eliminar dinámicamente el código y organizar los archivos javascript.Tenga en cuenta que una optimización importante para las aplicaciones web es reduce HTTP requests, por lo que a menudo conviene unir los archivos javascript más pequeños. (He encontrado que simplemente concatenar archivos js minimizados en un solo archivo, funciona muy bien)