Commentaires
- Veuillez spécifier la langue que vous souhaitez documenter, les standards et les outils varient selon les langues .
- Commencez par ceci: quest-ce que votre logiciel était censé résoudre / faire? Documentez les étapes à suivre pour cela avant tout.
- Veuillez trouver le code existant dans les projets open source existants. Veuillez lire ce code existant. Ensuite, comparez-le avec le vôtre. Enfin, après cela, posez des questions spécifiques basées sur le code que vous avez trouvé.
Réponse
Vous devez documenter:
- lintention, le pourquoi;
et
- ce qui peut ne pas soyez évident, le comment.
Pourquoi avez-vous optimisé ce bit, à quoi sert exactement ce raccourci, quel est le résultat que vous attendez, quelle est la condition requise, la raison pour laquelle il est là en premier lieu, où ces données sont-elles envoyées, doù proviennent les entrées, si cest multi-thread, expliquez le modèle, sil y a une base de données, expliquez le schéma, les liens, pourquoi …
Ne documentez pas lévidence. En ce qui concerne la présentation, il existe de nombreuses façons de le faire. Personnellement, jaime les commentaires en ligne (je suis un ancien type de programmeur et nous navions pas doutils sophistiqués à lépoque – plus je trouvez-le simple et direct). Si vous voulez quelque chose de sophistiqué, assurez-vous quil ne vous consomme pas trop de temps ou vous allez très probablement labandonner bientôt.
Commentaires
- Lintention est souvent la chose la plus utile, je peux regarder le code et comprendre ce quil fait, mais comprendre pourquoi le développeur la fait de cette façon peut être très utile.
Réponse
Lisez une partie de votre propre code que vous avez écrit il y a 2 ans ou plus.
Demandez-vous quels types de choses ne sont pas clairs et vous laissez vous gratter la tête lors de la lecture. Ces types de choses (quels quils soient, ils seront différents selon les programmeurs) sont ce que vous voulez commencer à documenter sur tout nouveau code que vous développez, ou ancien code que vous réécrivez / réutilisez. Tout formatage qui ralentit votre compréhension , changez.
Ou bien, dans 2 ans …
Réponse
Une chose que vous devriez include est les dépendances. Si une fonction repose sur quelque chose de là-bas alors doc ument ce que cest, où se trouve là-bas et pourquoi.
Réponse
Puisque vous « utilisez PHP, PHPDoc serait un bon point de départ. Vous pouvez créer la documentation de votre API en ligne dans la source, puis utiliser le même format pour rédiger des didacticiels et de la documentation utilisateur. Vous bénéficierez également dune certaine flexibilité en ce qui concerne le format de sortie.
Réponse
Je commence toujours à écrire du code en écrivant mes commentaires en premier. Décrivez le déroulement du programme, et vous commencerez à réaliser ce qui doit être commenté et ce qui ne lest pas. Une fois que vous avez commencé à écrire le code, vous embellissez les parties qui nécessitent des explications supplémentaires et affinez les parties qui se documentent automatiquement.
Une fois que chaque classe, fonction ou méthode est terminée, je reviens en arrière et ajoute des commentaires pour un générateur de documents comme doxygen ou PHPDoc. Cela vous donnera la documentation de lAPI réelle.
En fonction de la personne qui consomme mon code, jécrirai une description formelle du document dopération en LaTeX ou Word.
Réponse
Doxygen couvre la plupart des langues. Vous devrez passer un peu de temps à comprendre la syntaxe, mais le gros problème est de savoir quoi documenter. Traitez chaque fonction comme une boîte noire. Documentez ce qui entre et ce qui sort. Documentez les erreurs détectées, si les arguments peuvent être nuls, sil peut renvoyer une valeur nulle.
Noubliez pas que dans quelques mois seulement, vous ne serez pas en mesure de comprendre ce que fait une fonction. Vous ne faites que gagner du temps.