La documentation du logiciel est un texte écrit qui accompagne les logiciels informatiques. Il explique comment le logiciel fonctionne, comment l'installer, comment l'utiliser et d'autres ressources d'aide.
Beaucoup de gens affirment que "les commentaires devraient expliquer" pourquoi "mais pas" comment "". D'autres disent que "le code devrait être auto-documenté" et que les commentaires devraient être rares. Robert C. Martin affirme que (reformulé selon mes propres mots) souvent "les commentaires...
On m'a spécifiquement demandé de donner, ligne par ligne (ou selon le cas - par exemple, image par image, etc.) des explications ou des commentaires que mon supérieur souhaite pouvoir lire et suivre. Puisqu'il n'est pas programmeur, il ne peut pas suivre le code, il veut donc que tout soit traduit...
La norme RFC 2606 réserve les noms de domaine example.org , example.net et example.com dans le but de servir d'exemple dans la documentation. Quel est l’équivalent d’un numéro de téléphone (y compris le code du pays) qui peut servir d’exemple, par exemple pour donner aux utilisateurs un exemple...
Supposons que je développe un projet relativement important. J'ai déjà documenté toutes mes classes et fonctions avec Doxygen, cependant, j'ai eu l'idée de mettre une "note du programmeur" sur chaque fichier de code source. L'idée derrière ceci est d'expliquer en termes simples comment une classe...
Lors d'une réunion sur la restauration d'un SDK tiers à partir de la dernière version, il a été noté que nos développeurs avaient déjà signalé dans l'historique des validations que la dernière version ne devait pas être utilisée. Certains développeurs ont fait valoir que c'était une mauvaise...
Je travaille sur un assez gros projet et j'ai la tâche de faire quelques traductions. Il y avait des tonnes d'étiquettes qui n'ont pas été traduites et alors que je cherchais dans le code, j'ai trouvé ce petit morceau de code. //TODO translations Cela m'a fait réfléchir sur le sens de ces...
J'ai écrit le code suivant: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom());...
Tout d'abord, dans cette question, je voudrais rester à l'écart de la polémique sur la question de savoir si les commentaires sur le code source sont bons ou mauvais. J'essaie simplement de comprendre plus clairement ce que les gens veulent dire quand ils parlent de commentaires qui vous disent...
Je travaillais sur un projet il y a trois mois, puis, tout à coup, un autre projet urgent est apparu et on m'a demandé de déplacer mon attention. À partir de demain, je reviens à l'ancien projet. Je me rends compte que je ne me souviens pas de ce que je faisais exactement. Je ne sais pas par où...
Je prévois de quitter mon emploi actuel parce que nous sommes obligés d'utiliser Blub , avec un framework d'entreprise Blub et un serveur Web de niveau Blub, sur un hébergement mutualisé médiocre. Mes collègues sont sympathiques et mon patron est un propriétaire de petite entreprise moyen. Je veux...
Je comprends l'importance d'un code bien documenté. Mais je comprends aussi l’importance du code auto-documenté . Plus il est facile de lire visuellement une fonction particulière, plus nous pouvons avancer rapidement pendant la maintenance du logiciel. Cela dit, j'aime séparer les grandes...
La génération automatique de documentation peut être réalisée avec divers outils, GhostDoc étant l’un des plus importants. Cependant, par définition, tout ce qu’il génère est redondant. Il examine les noms de méthodes, de classes, etc. et génère un anglais qui pourrait les expliquer plus...
J'écris une documentation utilisateur (SOP) impliquant des programmes tiers que j'essaie de bien décrire. Un de ces programmes est un serveur qui offre peu d'indication sur son démarrage, outre un graphique qui apparaît au cours de sa routine d'initialisation / démarrage. En tant que développeur,...
Parfois, je me trouve dans des situations où la partie de code que j'écris est (ou semble être ) tellement évidente que son nom serait essentiellement répété sous forme de commentaire: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation...
Lorsque vous utilisez des outils tels que jsdocs , il génère des fichiers HTML statiques et leurs styles dans votre base de code en fonction des commentaires figurant dans votre code. Ces fichiers doivent-ils être archivés dans le référentiel Git ou doivent-ils être ignorés avec...
L’un des principaux objectifs des sociétés de développement de logiciels est d’augmenter leur facteur Bus. C’est également ce que préconise un exposé organisé par Google . Cela signifie que vous devez tout coder et documenter de manière à ce que le projet puisse continuer si vous êtes dépassé...
Il semble y avoir une aversion pour écrire même la documentation la plus élémentaire. Nos projets de lecture sont relativement nus. Il n'y a même pas de liste mise à jour des dépendances dans la documentation. Y a-t-il quelque chose que je ne connais pas dans l'industrie qui empêche les...
Lorsque je travaille sur du code, je suis confronté à bon nombre des mêmes problèmes que mes coéquipiers. J'ai également écrit des fonctions et des classes utiles. S'il y a une bonne communication, j'entendrai parler d'une bonne chose, mais six mois plus tard, quand j'en aurai besoin, je me...
Je me retrouve à écrire (espérons-le) des commentaires utiles dans la documentation de code (C ++) du type: The reason we are doing this is... La raison pour laquelle j'utilise "nous" au lieu de "je", c'est parce que je rédige beaucoup d'écrits académiques où "nous" est souvent préféré. Alors voici...
Le programme CS de mon école évite toute mention de la programmation orientée objet. Je me suis donc mis à lire moi-même pour la compléter, en particulier la Construction de logiciels orientés objet de Bertrand Meyer. Meyer insiste à plusieurs reprises sur le fait que les classes doivent cacher...