Questions marquées «documentation»

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 sont des excuses pour un code mal écrit". …

236 programming-practices  documentation  comments 

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 …

155 documentation 

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 dans quel …

112 documentation  standards  help-documentation 

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 spécifique fonctionne (et pas seulement …

104 documentation  large-scale-project 

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 pratique et que …

94 version-control  documentation 

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 …

86 documentation  comments 

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()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Il y a une ligne commentée ici. Mais je pense que cela rend le …

83 documentation  comments 

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 POURQUOI, …

78 documentation  comments 

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 …

72 project-management  documentation 

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 partir entièrement …

66 career-development  documentation 

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 fonctions en d'autres plus petites. Mais je le …

63 programming-practices  code-quality  documentation 

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 verbalement. Dans le meilleur des cas, …

60 documentation  automation  automatic-programming 

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, j’ai utilisé cette fenêtre comme …

59 documentation  component  jargon 

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 { get; set; …

54 programming-practices  documentation  language-agnostic 

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 .gitignore?

49 git  documentation