Documentation pour Open Source

Lorsqu'on veut rentrer dans un programme et faire une modification, ou tout simplement colaborer, si le programme est d'une bonne taille, ca devient difficile de comprendre les tenants et aboutissants du code.

J'aimerai mettre au point un méthode pour expliquer le code, je pense pour de l'Open Source. Et dire aussi comment et ou coder.

La question est donc pour expliquer votre code vous commenceriez par quoi (textuellement, car UML c'est jolie mais ca suffit pas).

Perso pour ma méthode OMOS (open method open source):
- je commencerai par expliquer l'architecture générale je crois (a plugin, event driven etc...)
- la délimitation et la responsabilité des couches
- la description détaillé de morceaux de code hardus
- des modes opératoires (façon de faire) sur comment si prendre pour rajouter des fonctions dans le respect de l'architecture (pour conserver de la cohérence).

Et vous ? Est ce que vous avez l'expérience de l'Open source ?

Ben désolé mais moins je décrirais pas mal de truc avec UML quand même : architecture, responsabilités des couches, packaging (composants, diagrammes de déploiement), interfaces, cinématiques (particulières et génériques comme les protocoles de dialogue à respecter entre N types de composants)

Ensuite, effectivement, j'illustrerai certains mécanismes de manière textuelle et avec des exemples de code afin que l'on comprenne comme cela est fait et comment il faudrait faire pour ajouter un truc du même genre par la suite = documentation par l'exemple.

Attention, je ne dénigre pas UML, c'est commode; c'est juste que ca suffit pas je trouve.

Je vois parfois des rapports de stages sur des projets, et on voit que tout le monde à le meme problème pour s'expliquer. Par ou commencer, jusqu'à quelle granularité faut il s'expliquer.

Je pense que de décrire des modes opératoires sur comment ajouter du code serait interessant.
Par exemple je voulais un editeur de texte donc j'ai regarder EKit; le code est attroce en faite. Et ca manque de documentation.

J'aurais eu besoin d'un mode opératoire pour ajouter un bouton. Ca aurait était plaisant qu'on me dise:
- dans la classe core déclarer votre bouton
- dans le package Action, déclarer une Action qui hérite TextAction etc...

ok avec ta remarque sur des docs genre "Comment faire ceci ?"
Mais un bon schéma UML permet au moins d'avoir une vision d'ensemble mais c'est vrai qu'illustrer les règles de conception c'est super important.

Il y a la méthode P+ qui est pas mal dès qu'il y a des IHM.

Fonctions

Ce document est le premier à être redigé. Il définie les grosses fonctionnalités de l'application.
Ce document sert notamment à :

• présenter la structure des traitements (appelé aussi fonctions) du système d'information au niveau utilisateur. Cette structure est utile pour définir la complexité de l'architecture ;
• présenter la structure de l'interface utilisateur.

Par exemple, pour la gestion d'une bibliothèque, on pourrait définir la fonction gererLivres qui regroupe
un ensemble de tâche unitaire (ou UT) qui permet de gérer les livres. Typiquement :creerLivre,listerLivreSelonCriteres...

On y met en général un schéma d'enchaînement des unités de tâches et un diagramme de cas d'utilisation.


Processus de travail

Ce document permet de~:

• décrire les utilisateurs du système, leur environnement de travail et les circonstances d'utilisation;
  
• définir les processus de travail et les unités de tâches associées executés par l'utilisateur.

Un processus de travail correspond à la manière dont l'utilisateur va utiliser l'application dans un certain cas.

Unité de tâche

Ce document permet de définir plus précisement une unité de tâche. On y décrit la raison d'être de l'unité de tâche, les
circonstances d'utilisation, les critères de qualités et la complexité.

On définit les cas d'utilisations (avec les droits) et le scénario nominal.

Pour l'exemple de l'UT listerLivreSelonCriteres, le scénario pourrait être :

• saisie des critères de recherche ;
  
• validation des critères de recherche ;
  
• affichage du résultat de la recherche.

Il est possible de compléter par un diagramme de séquences.
On définit ensuite plus précisement toutes les étapes de tâche : interface utilisateur nécessaire (avec éventuellement des maquettes), actions de
l'utilisateur, préconditions et postconditions, définition des services à utiliser.

On y met en général un diagramme d'activité.

Services

Les services vont correspondre directement à du code métier, il n'y a plus la notion d'utilisateur.
Les services pour un objet particulier sont en général regroupés dans une structure.

Pour reprendre l'exemple de l'application de gestion de livres, il est possible de définir un service
LivreServices qui va contenir un ensemble de services (parfois proche des UT), typiquement :

• recherche de livre ;
  
• mise à jour de livre ;
  
• suppression de livre ;
  
• création de livre ;
  
• emprunt de livre.

Une UT peut appeler plusieurs services.

Dans le document, on présente plus précisemment ces fonctionnalités en spécifiant :

• la raison d'être du service ;
  
• les post et préconditions ;
  
• les règles d'intégrité ;
  
• la complexité de développement ;
  
• les critères de qualité ;
  
• les dynamiques du services (l'algorithme)

On y met souvent des diagrammes de séquences.

Structure de l'information

Ce document est à rediger en parallèle avec les autres. Il définit la structure des données dans l'application.
Typiquement, cela correspond à un schéma conceptuel.
On définit ensuite chaque entité du schéma et leur raison d'être.

En reprenant l'exemple de la bibliothèque, on peut définir plusieurs entités, par exemple : client, livre...

On détaille précisemment chaque entité (raison d'être, champs, services, règles d'intégrité, volumes).

On y met en général des diagrammes de classes.

Persistence

Ce document permet de définir la structure physique de la base de données (si il y en a une).

Architecture

Ce document permet de définir l'architecture logicielle de l'application (sous-systèmes et composants logiciels).

Un lien vers un cours ?

Please