Meilleure façon de documenter le code AJAX + PHP?

Question

J'ai toujours été pour documenter le code, mais en ce qui concerne AJAX + PHP, ce n'est pas toujours facile: le code est vraiment étalé! La logique, les données, la présentation - vous l'appelez - sont divisées et mélangées entre le code côté serveur et le code client. Parfois, il y a aussi du code côté base de données (procédures stockées, vues, etc.) faisant partie du travail.

Cela me met au défi de trouver un moyen efficace de documenter un tel code. Je fournis généralement une liste de fichiers .js à l'intérieur du fichier .php ainsi que la liste des fichiers .php à l'intérieur du fichier .js. Je fais aussi des commentaires en ligne et des descriptions de fonctions, où j'énumère quelle fonction est utilisée par quel fichier et quelle sortie est attendue. Je fais des tâches similaires pour les procédures de base de données. Peut-être qu'il y a une meilleure méthode?

Des idées ou des expériences?

Remarque: Cette question s'applique à toutes les applications client + serveur, pas seulement Javascript + PHP.

Answer 1

Je pense qu'il est préférable d'adopter une approche hiérarchique.

Pour la documentation au niveau api comme au niveau de la fonction et la classe, écrire la documentation en ligne dans le code et générer de la documentation html sur leur utilisation des nombreux outils de documentation là-bas (JSDoc, phpDocumentor, OraDoclet, etc.). Points bonus si vos outils de documentation peuvent s'intégrer à vos outils de contrôle de code source afin que vous puissiez accéder à des lignes de code spécifiques à partir de vos documents d'api. Une fois que vous avez vos outils de documentation en place, commencez à générer la documentation dans le cadre de votre processus de construction (vous avez un processus de construction, n'est-ce pas?) Pour chaque nouvelle génération et déplacez la documentation vers un emplacement Web standard. Une fois que ces api docs sont en ligne, vous pouvez créer un wiki pour la documentation de haut niveau comme les interactions browser-> web-> db, les user stories, les diagrammes de schémas, etc. Il est préférable d'écrire en prose ou en puces pour documentation de haut niveau, liens vers des documents api et contrôle de la source si nécessaire.

Answer 2

Je pense que votre méthode est plutôt bonne. La seule chose est que tout ce qui se trouve dans le fichier js est lisible par d'autres et que documenter les fichiers PHP utilisés pourrait mener à un trou de sécurité, dans le cas où ils pourraient arriver à un fichier qui ne le devrait pas. Aussi, bien que ce ne soit pas un gros problème, sur les sites à fort trafic, le téléchargement dit que 500 octets de commentaires peuvent s'additionner.

Les deux ne sont pas grandes, mais juste des pensées que j'ai eues auparavant.

Answer 3

Servir votre javascript (et CSS) via PHP - vous pouvez garder vos fichiers source ensemble pour une référence croisée facile et avec une utilisation prudente des en-têtes, vous pouvez facilement gérer la mise en cache. Cela vous permet également de disposer d'une version source bien formatée et bien formatée que vous pouvez ensuite condenser ou masquer avant de l'envoyer au navigateur.

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

Pour les projets avec beaucoup de javascript, j'utiliser un système de construction (makefiles) avec un javascript minimizer. Comme le note l'auteur de jsmin, la suppression des commentaires «encourage un style de programmation plus expressif, car il élimine le coût de téléchargement d'une auto-documentation propre et bien documentée». Le bonus est que jsmin dépouille également les commentaires de CSS - ainsi vous pouvez commencer à commenter librement là aussi. (Je trouve que l'utilisation des classes css est cruciale pour écrire du javascript clair.)

C'est une idée intéressante d'utiliser PHP pour supprimer dynamiquement le code et organiser les fichiers javascript.Gardez à l'esprit qu'une optimisation importante pour les applications Web est de reduce HTTP requests, il est donc souvent judicieux de joindre des fichiers javascript plus petits ensemble. (J'ai trouvé que la simple concaténation des fichiers js minimisés en un seul fichier, fonctionne très bien.)