Projet Documentation

Question

J'ai un problème que je me sens beaucoup de programmeurs peuvent se rapporter à ...

Je travaille sur de nombreux projets à petite échelle. Après mon tempête de papier initiale, j'ai tendance à commencer à coder. Ce que je propose est généralement un modèle de travail approximatif de l'application réelle. Je conçois de manière déconnectée donc je parle de bibliothèques de code sous-jacentes, les interfaces utilisateur sont la dernière chose que la bibliothèque dicte habituellement ce qui est nécessaire dans l'interface utilisateur. Au fur et à mesure que mes projets prennent de l'ampleur, je m'inquiète aussi de mon «cahier des charges» ou document de conception.

Le paragraphe ci-dessus, de mes enquêtes, est répercuté partout sur l'Internet d'une manière ou d'une autre. Quand une interface utilisateur est concernée, il y a un peu plus d'informations mais il s'agit d'une interface spécifique et ne concerne pas les bibliothèques de code. Ce que je commence à réaliser est que peut-être le code est le code. Il semble de mes recherches approfondies qu'il n'y a pas de correspondance 1: 1 entre un document de conception et le code.

Quand j'ai besoin à la recherche d'un sujet que je largue des informations dans OneNote et à partir de là, je priorise des fonctionnalités dans les versions, puis en morceaux connexes afin que le développement fonctionne de façon assez linéaire, mes tâches ont tendance à ressembler à ceci:

1. Mettre en oeuvre lecteur de fichier binaire
2. Implémenter Binary File Writer
3. Créer un objet pour encapsuler les données d'expression à l'appelant

N De toute façon, tout programmeur digne de ce nom est conscient que, entre ces trois choses à faire, il pourrait y avoir un mur de code potentiel qui pourrait s'étendre à plusieurs fichiers. J'ai essayé de cartographier le processus de code complet pour chaque tâche, mais je ne pense tout simplement pas que cela peut être fait efficacement. Au moment où l'on mange le pseudo-code, il s'agit essentiellement de code de toute façon, donc l'investissement en temps est annulé.

Alors ma question est la suivante:

Suis-je raison de supposer que la meilleure documentation est le code lui-même. Nous sommes tous d'accord pour qu'une vue d'ensemble de haut niveau soit nécessaire. Quelle devrait être cette hauteur? Concevez-vous le niveau de déclaration, de classe ou de concept? Qu'est-ce qui fonctionne pour vous?

Answer 1

En fin de compte, je trouve qu'il ya quelques façons d'aborder ce, de cartes mentales aux schémas conceptuels et même code UML/pseudo. En fin de compte, ce qui fonctionne le mieux pour l'individu semble être la chose à utiliser.

Answer 2

Je vous recommande fortement de lire Code Complete 2 pour avoir un excellent aperçu de ce genre de questions.

http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670

Answer 3

Je pense que ce que vous voulez, c'est une spécification des exigences logicielles.

Coder toutes ces choses de manière chaotique est un mauvais moyen de faire le travail! Ce dont vous avez besoin est de créer une liste d'exigences fonctionnelles/non fonctionnelles pour créer une relation liée/parent/enfant/parent avec les exigences de l'interface utilisateur et pour l'acteur métier créer un cas d'utilisation. Après cette étape, vous devez éventuellement gérer toute l'interface de conception en code UML ou SPEUDO, mais lorsque vous êtes formalisé les exigences (pour un petit projet), le besoin d'avoir UML est supprimé.Pour la documentation du code, vous pouvez utiliser doxygen ou javadoc approche où, en bref, vous insérez un commentaire sur le code et avec un logiciel tout le doc est désactivé en HTML/PDF.

Avec cette façon, vous êtes atteint en séquence ce genre de choses:

1 - logiciel nécessaire
Maintenant, vous avez un aperçu complet de ce qui est votre logiciel et peut-être ce que fonctionnalités dont vous avez le logiciel besoin avec quelles contraintes (techniques/non -technique/temps/affaires). Et aussi cas de l'utilisateur pour tester le logiciel dans la dernière étape du cycle de vie du développement.

2 - Code UML ou PSEUDO
Un moyen facile de partager votre travail avec d'autres collègues et un simple aperçu du code de conception de l'interface de code. 3 - documentation de la bibliothèque pour d'autres codeurs comme vous et tous les avantages de ne pas perdre trop de temps à écrire tout le doc à la fin du projet!

mes 2 cents. Génie logiciel développement logiciel doxygen cycle de vie, CMMI, IEEE SRS (spécification des exigences du logiciel).