Documentation Soutenance - Département .Projet de développement Documentation Soutenance Philippe

download Documentation Soutenance - Département .Projet de développement Documentation Soutenance Philippe

of 16

  • date post

    10-Sep-2018
  • Category

    Documents

  • view

    214
  • download

    0

Embed Size (px)

Transcript of Documentation Soutenance - Département .Projet de développement Documentation Soutenance Philippe

  • Projet de dveloppement Documentation Soutenance

    Philippe Collet

    Licence 3 Informatique

    2012-2013

  • Ph. Collet 2

    Plan

    r Documentation : principes et outils

    r Contenu attendu pour le projet

    r Modalits de soutenance

  • Ph. Collet 3

    Pourquoi documenter (le code) ?

    r Ce que lon dcrit bien, se conoit bien !

    r Pour le prochain programmeur ou nous mme ?

    r Est-ce du temps perdu ? Et jusqu quel point documenter ?

    r Documenter, (une fonction) nest pas commenter! (le code)

  • Ph. Collet 4

    Problmatiques

    rProgrammeur : n Historique: qui/quand/quoi n Algorithme n Borne dutilisation n Paramtres n Valeur retourne n Structure du module n Mode dutilisation n Code derreur

    rMainteneur : n Historique: qui/quand/quoi n Documentation utilise jour n Que fait la fonction n Quel module utilise quelle

    fonction

    n Effet de cascade de la modification en cours

  • Ph. Collet 5

    Garder synchrone code et documentation

    r Une documentation obsolte est une documentation inutile

    r Documentation interne et extraction : n Commentaires formats n Graphe de dpendance entre les classes, les fichiers n Hirarchie de classes

    r Mais la documentation externe a des avantages n Lisibilit accrue n Synthse du logiciel

  • Ph. Collet 6

    Exemple : Javadoc

    r Extracteur spcialis java (trs simple) n Cohrence avec les conventions Java n Lancement possible sur toute une hirarchie n Production de html n Extensible avec des doclets (changement du format de sortie)

    getImage public Image getImage(URLurl, Stringname)

    Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument. This method always returns immediately, whether or not the image exists. When this applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

    Parameters: url - an absolute URL giving the base location of the image name - the location of the image, relative to the url argument

    Returns: the image at the specified URL

    See Also: Image

  • Ph. Collet 7

    Exemple : Javadoc (source)

    /** * Returns an Image object that can then be painted on the screen.

    * The url argument must specify an absolute {@link URL}. The name

    * argument is a specifier that is relative to the url argument.

    *

    * This method always returns immediately, whether or not the

    * image exists. When this applet attempts to draw the image on

    * the screen, the data will be loaded. The graphics primitives

    * that draw the image will incrementally paint on the screen.

    *

    * @param url an absolute URL giving the base location of the image

    * @param name the location of the image, relative to the url argument

    * @return the image at the specified URL

    * @see Image

    */

    public Image getImage(URL url, String name) {

    try {

    return getImage(new URL(url, name));

    } catch (MalformedURLException e) {

    return null;

    }

    }

  • Ph. Collet 8

    Exemple : Doxygen

    r Multi-langages n C++, C, Java, Objective-C, Python, IDL (Corba et Microsoft) n partiellement PHP, C#

    r Multi-plates-formes n Unix, Windows

    r Multi-sorties n HTML, LaTeX (PDF), RTF, Man, XML, Aide Windows

    r Traitements plus labors : n Fichier de configuration, assistant d'aide la configuration n Gnration de graphes avec graphviz/dot n Gnration d'un moteur de recherche (pour site web avec PHP)

  • Ph. Collet 9

    Doxygen : graphes

    r Hirarchie de classes

    r Graphes dinclusion

    r Graphes de collaboration

    r Graphes dappel

  • Ph. Collet 10

    Exemple : PhpDocumentor

    r Outil de documentation crit en PHP n semblable l'outil de javadoc n travaille par analyse des commentaires et du code n Open source (licence LPGL)

    r Fonctionnalits n Gnration de documentation du code ralis en objet ou procdural n Formats d'exports : HTML, PDF, CHM ou docbook

    r www.phpdoc.org

  • Ph. Collet 11

    Exemple : PhpDocumentor

    class class1 { /** * example of documenting a method, and using optional description with @return * @return string de-html_entitied string (no entities at all) */ function bar($foo) { return strtr($foo,array_flip(get_html_translation_table(HTML_ENTITIES))); } /** * example of using @return with a class name * @param integer even or odd integer * @return Parser|false phpDocumentor Parser object or error */ function &factory($number) { $returnval = true; if ($number % 2) { $returnval = new Parser; } else { $returnval = false; } return $returnval; } }

  • Application votre projet : soutenance

  • Ph. Collet 13

    Rsultat attendu

    r Chaque projet doit rendre accessible, avant la soutenance, les informations suivantes :

    n Redmine : u Wiki : au moins la page principale dite pour synthtiser les grands choix de conception,

    les fonctionnalits livres, les problmes rencontrs, etc.

    u Jalons (milestones / version) dtermins dans le projet (a priori ou a posteriori, l'essentiel tant de communiquer sur ces jalons)

    u Identification des tches individuelles ou en binme : ticket (fonctionnalits, bugs corrigs...)

    u Chaque ticket ferm correspondant du dveloppement doit correspondre une version sur le subversion

    u Les runions doivent aussi faire l'objet d'un compte-rendu (ticket runion spcifique), que ce soit pour une runion avec prise de dcision au sein du groupe ou avec l'encadrant.

  • Ph. Collet 14

    Rsultat attendu : subversion

    r Tout le code doit tre document raisonnablement (pages et classes PHP) : entte du module/classe, commentaire sur les fonctions/oprations les plus importantes

    r De la mme manire, les fonctionnalits les plus critiques doivent tre forcment testes (plus une

    fonctionnalit est critique ou vous a pos de problmes, plus on s'attend la voir fortement teste). Etre capable de passer l'ensemble des tests crits sur votre projet fait partie des rsultats attendus (il doit donc

    y a voir de la documentation pour expliquer comment faire). De plus, il est aussi attendu que l'quipe

    puisse argumenter ses choix de test (pourquoi telle ou telle partie a t plus ou moins teste et comment).

    r Chaque commit doit avoir un commentaire associ (ce commentaire n'a pas a tre trs long, surtout si la fermeture d'un ticket correspond au commit)

    r La dernire version excutable et testable doit tre identifie le jour de la soutenance (pour tre

    justement excute et teste)

    r Si une bd est utilise : un export sql (avec des donnes l'intrieur) et les paramtres par dfaut de la

    connexion la bd doit tre soit dans le svn soit dans le redmine : il faut que dans la page wiki on trouve

    toutes les informations d'installation et de configuration (y compris la bd)

  • Ph. Collet 15

    Soutenance

    r Chaque soutenance dure 25 minutes

    r 15 minutes de prsentation : chaque prsentation doit faire intervenir tous les membres de l'quipe de faon quivalente. Le plan suivant est conseill :

    n Introduction et rappel du sujet n Fonctionnalits ralises : bilan gros grain de ce qui a t fait, est rest en chantier, a t

    cart par rapport ce qui tait attendu (dmo possible mais pas obligatoire)

    n Grands choix de conception et approche suivie : les jalons et tickets doivent vous servir facilement tablir, au fur et mesure de votre avancement, les lments mettre en avant dans cette partie

    n Problmes rencontrs et solutions apportes (correction, changement dans la conception, abandon d'une fonctionnalit...)

    n mini-dmo finale (attention au timing)

    r 10 minutes de question : n Chaque membre du projet doit tre capable de rpondre aux questions sur les choix de

    conception gnraux, les parties qu'il a dveloppes, etc.

  • Ph. Collet 16

    Questions

    http://deptinfo.unice.fr/twiki/bin/view/Linfo/ProjetInfo201213Soutenance

    Rappel des dates importantes : lundi 17 dcembre 2012 23h59 : arrt du dveloppement (site de gestion

    du projet, ticket, et des sources) mercredi 19 dcembre 2012 9h59 : arrt des modifications sur le site wiki

    pour expliquer le projet et prparer les infos de prsentation : les transparents (pdf, open-office ou powerpoint 2010 PC) sont mettre dans le redmine, dans "fichier"