Hyperlien, documentation externalisée sur le code source [fermé]

Pourquoi incorporons-nous toujours des descriptions en langage naturel du code source (c.-à-d. La raison pour laquelle une ligne de code a été écrite) dans le code source, plutôt que comme document séparé?

Compte tenu de l'immobilier étendu offert aux environnements de développement modernes (moniteurs haute résolution, doubles moniteurs, etc.), un IDE pourrait fournir des panneaux à demi-verrouillage dans lesquels le code source est visuellement séparé de - mais intrinsèquement lié à - ses commentaires correspondants. Par exemple, les développeurs pourraient écrire des commentaires de code source dans un langage de balisage hyper-lié (reliant à des exigences logicielles supplémentaires), ce qui empêcherait simultanément la documentation d'encombrer le code source.

Quelles lacunes empêcheraient un tel mécanisme de développement logiciel?

Une maquette pour aider à clarifier la question:

Lorsque le curseur se trouve sur une ligne particulière du code source (illustré avec un arrière-plan bleu, ci-dessus), la documentation qui correspond à la ligne sur le curseur est mise en surbrillance (c'est-à-dire qu'elle se distingue des autres détails). Comme indiqué dans la question, la documentation resterait en phase de verrouillage avec le code source lorsque le curseur saute dans le code source. Un raccourci clavier pourrait basculer entre le "mode de documentation" et le "mode de développement".

Les avantages potentiels incluent:

• Plus de code source et plus de documentation sur les écrans à la fois
• Possibilité de modifier la documentation indépendamment du code source (quelle que soit la langue?)
• Écrire de la documentation et du code source en parallèle sans conflits de fusion
• Documentation hypertexte en temps réel avec un formatage de texte supérieur
• Traduction automatique en temps quasi réel dans différentes langues naturelles
• Chaque ligne de code peut être clairement liée à une tâche, une exigence métier, etc.
• La documentation peut horodater automatiquement lorsque chaque ligne de code a été écrite (métriques)
• Inclusion dynamique de diagrammes d'architecture, d'images pour expliquer les relations, etc.
• Documentation à source unique (par exemple, extraits de code de balise pour inclusion dans le manuel de l'utilisateur).

Remarque:

• La fenêtre de documentation peut être réduite
• Le flux de travail pour afficher ou comparer les fichiers source ne serait pas affecté
• Comment l'implémentation se déroule est un détail; la documentation pourrait être:
  • conservé à la fin du fichier source;
  • divisé en deux fichiers par convention ( filename.c, filename.c.doc); ou
  • entièrement basé sur la base de données
• Par documentation hyperliée, j'entends la création de liens vers des sources externes (telles que StackOverflow ou Wikipedia) et des documents internes (c'est-à-dire un wiki sur un sous-domaine qui pourrait renvoyer à la documentation des exigences commerciales) et à d'autres fichiers source (similaires à JavaDocs).

Fil connexe: Quelle est l'aversion pour la documentation dans l'industrie?

Ce problème me dérange tout le temps, et je viens de me faire une idée de la direction que nous devrions essayer de résoudre (c'est ainsi que j'ai trouvé cette question).

Je pense que le problème de documentation liée a été mal pensé lorsque nous avons décidé d'inclure la documentation utilisateur dans le code source. Comme le fait Docco.

Tout d'abord, permet de différencier les commentaires de code de la documentation utilisateur.

Les commentaires de code sont normalement à leur meilleur quand ils sont courts, super courts en fait, donc je peux réellement lire le code qui fait le truc sans avoir à voir de la poésie pourquoi et comment cela fonctionne.

Les commentaires des utilisateurs sont destinés aux personnes essayant d'utiliser votre bibliothèque / API, et peuvent inclure des exemples d'utilisation, une explication de la raison pour laquelle elle a été implémentée de cette façon, ou des instructions sur la façon d'étendre la bibliothèque. Ce genre de commentaires a tendance à être très verbeux.

Je suis d'accord sur le fait que la documentation doit être écrite en texte clair, donc elle n'est pas corrigée par le fournisseur et il est facile de l'ajouter dans un VCS. Mais je pense que garder la documentation utilisateur dans le fichier source était une grosse erreur pour au moins deux raisons:

• Code plus difficile à lire
• Documentation pas assez flexible (supposons que j'ai besoin de deux pages de documentation utilisant le même exemple de code ou ayant une page de documentation devant entrelacer le code de deux fichiers source différents).

Alors pourquoi voulons-nous l'avoir dans le même fichier? Eh bien, personne ne veut que ses documentations soient désynchronisées du code. Mais nous le faisons quand même, et surtout maintenant quelques jours avec le grand succès de Markdown. Ce qui, je pense, est sur la bonne voie, mais s'il échoue, waaay court.

Lorsque nous entrelacons un commentaire de code avec un commentaire d'utilisateur, nous avons une liaison bidirectionnelle. Cela nous permet de voir facilement quel commentaire correspond à quelle partie du code. Nous pouvons également voir si du code n'est pas documenté. Ce qu'il n'offre pas, c'est un moyen de voir si le commentaire est mis à jour ou non, et cela arrive souvent lorsque votre code est difficile à lire (parce que la documentation le rendait laid).

Que se passe-t-il si, au lieu d'avoir une liaison bidirectionnelle, nous avons une liaison unique?. Documentation pointant vers du code. Nous pourrions avoir du code de démarque avec des commandes spéciales comme:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Cela a l'avantage d'être balisé avec certains ajouts, et avec les outils appropriés, nous pourrions y ajouter plus de valeur.

Imaginez cette liaison à sens unique avec des outils comme grognement (même avec la tâche de surveillance). Vous pouvez détecter quand un fichier source change, voir quels fichiers de documentation en dépendent et avertir l'utilisateur (ou le marquer quelque part) si le code qui a été commenté a changé.

404 Page non trouvée

Lorsque vous travaillez avec du code, vous ne voulez pas que vos commentaires soient perdus et c'est ce qui se passera lorsque vous séparerez le code et les commentaires dans des documents séparés.

De plus, le maintien du contrôle de version entre votre document de commentaire et votre document de code causera plus de douleur que de gain.

Certaines des suggestions que vous faites me plaisent beaucoup, mais pourraient facilement être mises en œuvre tout en ayant du code et des commentaires dans un fichier.

Inconvénients possibles que je vois:

• Vous avez besoin d'un éditeur spécial qui implémente cette fonctionnalité

• Le code n'est plus seulement du texte brut, facile à manipuler et à valider sur VCS-es

• Vous avez besoin de deux fois plus de largeur d'écran pour travailler avec le code

Quant à vos arguments:

Plus de code source et plus de documentation sur les écrans à la fois

Mais cela peut être gênant si vous souhaitez afficher deux fichiers côte à côte.

Possibilité de modifier la documentation indépendamment du code source (quelle que soit la langue?)

Je dirais que c'est en fait un inconvénient. J'essaie personnellement de garder la documentation aussi proche que possible du code, afin qu'il ne devienne pas obsolète.

Écrire de la documentation et du code source en parallèle sans conflits de fusion

Encore une fois, peut-être un inconvénient. Si vos documents sont profondément entrelacés avec du code, comment pouvez-vous les éditer indépendamment?

Documentation hypertexte en temps réel avec un formatage de texte supérieur

S'il est dans le code, il est déjà en temps réel;) Comme pour les hyperliens, le saut à la définition est déjà implémenté dans la plupart des IDE.

Traduction automatique en temps quasi réel dans différentes langues naturelles

Je ne vois pas pourquoi vous ne pouvez pas faire ça avec des commentaires / docstrings réguliers.

Chaque ligne de code peut être clairement liée à une tâche, une exigence métier, etc.

Je ne suis pas sûr de cela ... Cela ne peut-il être réalisé avec des commentaires réguliers?

La documentation peut horodater automatiquement lorsque chaque ligne de code a été écrite (métriques)

VCS-es ne fournit-il pas déjà ce type d'informations?

Cela dit, j'aime bien la mise en page elle-même - mais je ne vois pas la nécessité de changer le format de fichier, ce n'est pas si difficile de le générer à partir de commentaires réguliers. Il y a un tas de générateurs de documentation qui font cela, par exemple Docco et ses successeurs, comme Pycco ou Marginalia .

Tout d'abord, les commentaires de doc doivent être accompagnés du code - les déplacer ailleurs ne fait que rendre les choses incroyablement difficiles à gérer pour un gain pratiquement nul. Alors pourquoi s'embêter!

Ce qui pourrait être fait, cependant, est de prendre ces commentaires intégrés et de les masquer dans l'éditeur, en les montrant dans une bulle ou une info-bulle ou autre chose selon les besoins. J'espère qu'une telle approche pourrait encourager les gens à écrire beaucoup plus de documentation sur le code - par exemple, une description d'une classe pourrait aller avec la classe plutôt que dans un document de conception externe.

Vous pouvez actuellement intégrer des hyperliens dans les commentaires de code et vous pouvez générer des documents à partir du code à l'aide d'outils tels que Doxygen ou Sphinx. Je suppose qu'il faudrait juste une extension sophistiquée à l'éditeur de code pour mieux prendre en charge ces outils.

Je ne lierais aucune ligne de code à un outil de suivi des bogues ou d'exigences, c'est un meilleur travail pour votre SCM. Ensuite, vous pouvez voir les modifications de code par validation liées à une tâche. Je n'intégrerais pas non plus la documentation stockée dans le code contre le traqueur de bogues - vous seriez foutu si vous vouliez migrer vers une nouvelle (hmm, je peux voir cette fonctionnalité ajoutée à TFS en ce moment) ou si vous perdu votre historique de commit (ce qui arrive)

Outre ce que @Bogdan déclare déjà, j'en ajouterais quelques-uns:

• J'ai configuré mon IDE pour toujours avoir 2 fichiers à la fois. Avec la fonctionnalité que vous proposez, j'aurais essentiellement besoin de 2 moniteurs pour voir la même quantité d'informations, et 3 pour faire ce que je fais maintenant avec 2.
• Lorsque vous parcourez un fichier, vous ne voyez pas immédiatement les commentaires, et si vous ne savez pas exactement ce que vous recherchez, il est très difficile de le trouver.
• Lors de la recherche dans un fichier, je ne peux pas rechercher les commentaires directement (ou aussi facilement).
• J'ai parfois besoin de faire divers tests / écrire de courts morceaux de code sur le serveur en direct, via ssh . Bien que la fonctionnalité que vous dites pourrait être intégrée à VIM ou à d'autres éditeurs de ligne de commande - il y aurait très probablement de gros problèmes

• La plupart des IDE prennent en charge la réduction du code / des commentaires , les résultats finaux étant les suivants:

  Au lieu de la normale:

  

Rendez le code plus lisible, au cas où vous n'auriez pas besoin des commentaires.

Le code source et la documentation comme cela devrait être fait.

http://jasmine.github.io/2.3/introduction.html