+ Répondre à la discussion Actualité déjà publiée
Page 1 sur 4 1234 DernièreDernière
  1. #1
    Chroniqueur Actualités
    Avatar de Patrick Ruiz
    Homme Profil pro
    Rédacteur technique
    Inscrit en
    février 2017
    Messages
    301
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : Cameroun

    Informations professionnelles :
    Activité : Rédacteur technique
    Secteur : Communication - Médias

    Informations forums :
    Inscription : février 2017
    Messages : 301
    Points : 9 700
    Points
    9 700

    Par défaut La notion de code source autodescriptif relèverait d’un mythe

    La notion de code source autodescriptif relèverait d’un mythe
    Entretenu par les programmeurs qui n’ont pas saisi la portée de « documenter »

    En programmation, l’écriture de code autodescriptif est une pratique qui implique le respect de certaines conventions de nommage et de programmation structurée. Eric Holscher affirme qu’il y a un amalgame au sein de la communauté des programmeurs en ce qui concerne cette pratique. Ce mélange a – de son point de vue – un impact négatif sur l’utilisabilité des logiciels et applications mis à disposition des personnes sans compétences en programmation.

    Eric Holscher – cofondateur de ReadTheDocs, un service en ligne qui héberge de la documentation pour l’industrie du logiciel – entame son propos par une explication de la notion de commentaires. De son point de vue, ces derniers sont un sous-ensemble de la documentation qui devrait accompagner toute œuvre du génie logiciel.

    Il va plus loin en ajoutant que ce sous-ensemble particulier est destiné à « documenter le pourquoi et non le comment », c’est-à-dire à : expliquer de précédentes approches qui n’ont pas fonctionné, faire apparaître de possibles améliorations, expliquer les compromis dans l’implémentation en cours, etc.

    Ce sous-ensemble est à mettre en cohabitation avec les conventions de nommage et de programmation structurée au sein du code. Ces dernières viendraient ainsi jouer leur rôle qui est – selon lui – de « documenter le comment et non le pourquoi ».

    Il semblerait cependant que certains programmeurs fassent fi de ce jeu de rôle et se limitent uniquement au respect des conventions de nommage et de programmation structurée pour affirmer que leur code source est « autodescriptif ». « Je n’ai plus besoin d’expliquer quoi que ce soit puisqu’il est désormais évident que le fonctionnement du programme est accessible à tous », leur attribue-t-il alors.

    « Décider que les noms de variables [la convention de nommage] constituent la seule documentation requise signifie que seules les personnes qui lisent le code source peuvent en faire usage », déclare Eric Holscher pour s’indigner du fait que la documentation s’adresse en principe aux « utilisateurs de tous bords ».

    Eric Holscher met ainsi de l’emphase sur le fait que la documentation du code va bien au-delà de la mise en œuvre du tandem de règles précédemment mentionné. Se limiter à respecter ces règles conduirait fatalement à exclure les personnes sans compétences en programmation de la liste des potentiels utilisateurs.

    Il y a donc plus à faire que mettre côte à côte la « documentation du pourquoi et non du comment » et celle du « comment et non du pourquoi ». Il faudrait en plus penser à l’intégration d’éléments comme les tutoriels susceptibles de booster l’utilisabilité du logiciel ou de l’application déployée.

    « Si vous tenez à avoir des utilisateurs pour les œuvres que vous produisez, il va falloir rédiger de la documentation », a-t-il conclu.

    Source : blog

    Et vous ?

    Qu’en pensez-vous ?
    Vous arrive-t-il de ne faire usage que des conventions de nommage au détriment des commentaires ?
    Partagez-vous l’avis de l’auteur sur la portée qu’il attribue à la notion de documentation en génie logiciel ?

    Voir aussi :

    Programmation : quand faut-il commenter son code ? Google s'invite dans le débat et montre que les commentaires peuvent très souvent être évités
    Débat qualité développement : Faut-il commenter son code source pour le rendre plus lisible et plus facile à maintenir ? Si oui comment ?
    Contribuez au club : Corrections, suggestions, critiques, ... : Contactez le service news et Rédigez des actualités

  2. #2
    Expert confirmé
    Avatar de TiranusKBX
    Homme Profil pro
    Développeur C, C++, C#, Python, PHP, HTML, JS
    Inscrit en
    avril 2013
    Messages
    1 473
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 28
    Localisation : France, Seine et Marne (Île de France)

    Informations professionnelles :
    Activité : Développeur C, C++, C#, Python, PHP, HTML, JS
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : avril 2013
    Messages : 1 473
    Points : 4 924
    Points
    4 924
    Billets dans le blog
    6

    Par défaut

    Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?
    Le nom des variable si il doit être commenté c'est en doc technique pour une utilisation en tant que Lib ou pour les futurs mainteneurs du programme, pas pour une utilisation tout public.
    Pour les programme de ma boite on tire au sort(3 programmeurs, le choix est rapide) qui vas faire la doc de nos programmes(pas pour les programmes de commande, le cahier des charges fait office de DOC et à chaque modifications le client doit le mettre à jour)
    merci de me mettre des quand mes messages sont pertinent, et pour les pas contents voici mon service client pour eux

    [Projet en cours] Strategy(nom provisoire) - Advance wars like
    cordova-plugin-file-hash Plugin cordova servant à obtenir le hash d'un fichier

  3. #3
    Membre confirmé
    Homme Profil pro
    Étudiant
    Inscrit en
    juin 2008
    Messages
    504
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : Étudiant

    Informations forums :
    Inscription : juin 2008
    Messages : 504
    Points : 625
    Points
    625

    Par défaut

    Citation Envoyé par Patrick Ruiz Voir le message
    En programmation, l’écriture de code autodescriptif est une pratique qui implique le respect de certaines conventions de nommage et de programmation structurée. Eric Holscher affirme qu’il y a un amalgame au sein de la communauté des programmeurs en ce qui concerne cette pratique. Ce mélange a – de son point de vue – un impact négatif sur l’utilisabilité des logiciels et applications mis à disposition des personnes sans compétences en programmation.
    Pour les logiciels et applications, l'utilisateur n'a rien a faire du code source et de ses commentaires. Pour une lib, le problème commence a survenir, mais il y a deux choses à distinguer : l'interface utilisateur, i.e. ce à quoi la lib donne accès et l'implem. Là, l'utilisateur n'a rien à faire de l'implem, qui est potentiellement privée. La documentation de type doxygen est peut -être utile, mais je préfère un petit tuto/exemple de base et des noms de fonctions explicites qui me permettent de ne pas consulter la doc, sauf dans des cas très particuliers. Documenter l'opération addition sur des entiers, ça n'a pas d'intérêt, documenter les opérations matricielles pour une lib de math, ça n'a pas d'intérêt, par contre documenter la différence entre deux manières différentes de construire une matrice peut être intéressant quand l'une est beaucoup plus rapide que l'autre.
    raphchar

  4. #4
    Membre actif Avatar de der§en
    Homme Profil pro
    Développeur informatique
    Inscrit en
    septembre 2005
    Messages
    256
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 53
    Localisation : France, Seine et Marne (Île de France)

    Informations professionnelles :
    Activité : Développeur informatique
    Secteur : Services de proximité

    Informations forums :
    Inscription : septembre 2005
    Messages : 256
    Points : 205
    Points
    205

    Par défaut

    cofondateur de ReadTheDocs, un service en ligne qui héberge de la documentation pour l’industrie du logiciel : il me semble que tout est dit sur la raison de ces propos.

    Je lui conseillerait de lire l'excellent Coder proprement.

  5. #5
    Membre confirmé
    Profil pro
    Inscrit en
    mai 2011
    Messages
    276
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : mai 2011
    Messages : 276
    Points : 585
    Points
    585

    Par défaut

    J'etais jeune et je croyais aussi que le code commente ou la documentation ne servait a rien.

    Je vais entendre dans ce post, les trucs classqiues :
    • Pas le temps de commente le code ou faire de la documentation
    • Pas besoin de commenter, le code est lisible
    • Il faut poser plus de questions


    Enfin bon je vais evaluer ces trois points que j'entends souvent. Je pense qu'il y en a plus mais c'est les plus frequent.
    Quand j'ai rejoint une companie super structure, j'ai decouvert ce qu'on peut etre le dilema pyramidale qu'on pouvait retrouvez chez big-blue ou dans les entreprises japonnaises.

    Pas le temps de commente le code ou faire de la documentation
    Je voudrais quand j'etais nouveau dans l'entreprise, j'ai aussi eu le cas, "Regarde la documentation (plutot : demerdes toi ...), je suis occupe pour le moment". Ironique non ...
    Heuresement, pour moi ils avaient fait de la documentation . Et cette grace a cette doc que j'ai pu avance a mon travail, en posant les question sur le detail qui ets manquant et crucial sur un projet.
    Dans le travail, je considere deux methodes car chaque personne a differente personnalite, culture, formation et curiosite.
    Vous avez ceux qui cherchent et ceux qui cherchent pas, ceux qui osent poser des questions et ceux qui le font pas. Combien de fois j'ai entendu, oh regarde le jeune il pose beaucoup de questions ... Par contre dans le monde anglosaxons, Oh putains ils posent pas de question du tout.

    La documentation est neccessaire peu importe le gens avec qui vous travailles, pour laisser des traces (procedure judiciaire, support techniques car vous travaillez pas tout seul, aide pour le stagiaire pour son rapport, echange ou vente de competence), pour comprendre un mecanisme. A chaque fois, j'entends toujours les memes dire, que le cas particuliers ne viendra jamais.

    Par exemple, prenez un gars qui comme moi n'a pas d'experiences mais qui apprend super vite en observant et lisant les documentations pour rendre le produit sien. Certaines boites qui ont tendances a ne pas faire de docs auront tendances a vouloir recruter des seniors, des gens de prepas ou des gens avec 5 ans d'experiences, en gros le mouton a 5 pattes. Pourquoi, tout simplement parce qu'ils veulent pas formes. Dans cas la, je peux comprendre, mais on ferme des portes a gens qui peuvent etonner si on prend les mesures neccessaire pour le partage de connaissance. J'ai vu a sa Londres, et soi-disant ils ont "des penuries" (what a joke).

    La documentation a des vertus plus pointus qu'on ne le pense quand on maitrise l'art du business et du management. Et personnellement, je pense qu'un developpeur qui fait que DE coder ne peut pas comprendre ces aspects car il a tres peu de chance de l'avoir appris.


    Pas besoin de commenter, le code est lisible
    Comme certain l'a expliquer, le but de dire Why ? C'est simplement d'expliquer le mecanisme. Prenons le cas d'une fontion :
    Ok le but c'est de comprendre ce qu'il fait, ce qu'il returne.
    Pour l'instant, on peut le dire comme sa :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    void afficher(stream output, stream content);
    Bon c'est un peu mieux, on peut comprendre comment ce a besoin, ce qu'il ressort. Ok c'est cool sur un logiciel, un site-web, une application mobile, le classic quoi ...


    Je n'ai pas plus le livre "Clean Code" ou encore "Refactorisation" (trop cher et trop gros :p). J'ai lu par contre celui la : "Practical Object Oriented Design in Ruby". Dans dix ans ou moi je suis parti a la retraite deja, je vais mettre mon application en VR (virtual reality). Sauf que le mechanisme interne que j'ai cree n'est pas du tout pour ce cas. Comment mon remplacent va devoir regler le probleme. Le meme probleme qui se pose quand un de vos services (operateur telephonique, service apres-vente, ...) fait pas bien son boulot, vous devriez pas faire pareil. Dite-vous que cela peut etre vous qui aller continuer ce projet, alors fiates les proprement.


    Il faut poser plus de questions
    Je ne sais pas quoi dire, a part que "officiellement", toutes questions ne sont pas idiotes. En realite ..., toutes les questions font **** tout le monde. Culture d'entreprise, culture francaise, culture de gars en costard, culture du "camra cafe". Je m'avancerais pas a point. Je ne suis pas magicien.

    En somme :
    La documentation est super importante, vous cherchez juste des excuse pour ne pas la faire. Mais toutes les vertus sont la. Le context pour le faire differt mais c'est une question de management. Et je pense que faire le radin ne resoudra rien sur le long terme.

  6. #6
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    575
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 575
    Points : 594
    Points
    594

    Par défaut

    Citation Envoyé par Patrick Ruiz Voir le message
    Se limiter à respecter ces règles conduirait fatalement à exclure les personnes sans compétences en programmation de la liste des potentiels utilisateurs.
    Heu, il y a une limite quand même…*Ce n'est pas le job du développeur et du code d'enseigner la programmation… Il est quand même attendu de celui qui met la main dans le code ou qui utilise ce code qu'il ai une compétence en programmation. D'ailleurs, Eric Holscher ne parle pas de personnes sans compétence en programmation mais des développeurs qui ne sont pas les développeurs du code en question…

    Partagez-vous l’avis de l’auteur sur la portée qu’il attribue à la notion de documentation en génie logiciel
    La documentation au sens large reste indispensable, que ce soit la documentation des fonctions/classes/modules que les commentaires. Anecdote personnelle : un "architecte" qui me pond une méthode et me dit "tu verra dans la signature comment elle s'utilise"… Ben non patate, ta collection en second paramètre, on sait que de temps en temps elle n'a rien, on peut lui passer un Null ? Idem en retour, quand il n'y a rien, c'est une collection vide ou Null (oui je parle de ce langage NullPointerExceptionGenerator )…

    Le problème de cette mouvance résulte surtout des pseudo-agilistes qui ont omis dans "Des logiciels opérationnels plus qu’une documentation exhaustive" le mot "exhaustif" et qui retiennent "pas de documentation"…

    Citation Envoyé par TiranusKBX Voir le message
    Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?
    Quand on regarde la source, non, c'est le relais sur Developpez qui est mal rapporté.

  7. #7
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    575
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 575
    Points : 594
    Points
    594

    Par défaut

    Citation Envoyé par der§en Voir le message
    cofondateur de ReadTheDocs, un service en ligne qui héberge de la documentation pour l’industrie du logiciel : il me semble que tout est dit sur la raison de ces propos.

    Je lui conseillerait de lire l'excellent Coder proprement.
    Tu ne connait pas ReadTheDocs toi…

  8. #8
    Expert confirmé
    Homme Profil pro
    Analyste/ Programmeur
    Inscrit en
    juillet 2013
    Messages
    2 129
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Analyste/ Programmeur

    Informations forums :
    Inscription : juillet 2013
    Messages : 2 129
    Points : 4 741
    Points
    4 741

    Par défaut

    Citation Envoyé par martopioche Voir le message
    Le problème de cette mouvance résulte surtout des pseudo-agilistes qui ont omis dans "Des logiciels opérationnels plus qu’une documentation exhaustive" le mot "exhaustif" et qui retiennent "pas de documentation"…
    Il me semble que les tests unitaires peuvent faire office de documentation

  9. #9
    Provisoirement toléré

    Profil pro
    Inscrit en
    juin 2003
    Messages
    366
    Détails du profil
    Informations personnelles :
    Âge : 41
    Localisation : France, Pyrénées Orientales (Languedoc Roussillon)

    Informations forums :
    Inscription : juin 2003
    Messages : 366
    Points : 0
    Points
    0
    Billets dans le blog
    1

    Par défaut C'est quoi le code source ?

    La bonne question est de ce poser c'est quoi un code source , un programme informatique, c'est quoi la différence entre le langage naturel et le langage de programmation.
    Quand on a passer comme moi plus de 25 ans à coder, j'ai trouvé le code source est juste la représentation formel sans ambiguïté et déterministe du langage naturel.
    Donc la question est simple pourquoi donc documenter/commenter un programme et ben il y a aucune raison pour le faire.
    Mais en réfléchissant plus la seul et unique raison après pour commenter/documenter un programme est de prendre conscience que le développeur qui reprendra le code sera peut-être un boulet avec peut de capacité de compréhension limité.
    Donc pour tous les développeurs amateurs ,incompétent et limité il faut forcement documenter/commenter son code.

  10. #10
    Membre chevronné
    Avatar de Pyramidev
    Homme Profil pro
    Développeur
    Inscrit en
    avril 2016
    Messages
    447
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Val de Marne (Île de France)

    Informations professionnelles :
    Activité : Développeur

    Informations forums :
    Inscription : avril 2016
    Messages : 447
    Points : 1 960
    Points
    1 960

    Par défaut

    Citation Envoyé par martopioche Voir le message
    Anecdote personnelle : un "architecte" qui me pond une méthode et me dit "tu verra dans la signature comment elle s'utilise"… Ben non patate, ta collection en second paramètre, on sait que de temps en temps elle n'a rien, on peut lui passer un Null ? Idem en retour, quand il n'y a rien, c'est une collection vide ou Null (oui je parle de ce langage NullPointerExceptionGenerator )…
    Dans un langage comme le Java ou le C qui contient le type "référence qui peut être nulle" sans contenir le type "référence forcément non nulle", en pratique, la plupart des fonctions qui retournent des références retournent des références jamais nulles et la plupart des appels des fonctions sont pensés comme si les arguments n'étaient jamais nuls.
    Du coup, à mon avis, avec un tel langage, le mieux est d'adopter une convention qui stipule que toutes les références sont non nulles par défaut. Si une fonction peut retourner une référence qui peut être nulle, il faut alors le signaler explicitement, par exemple avec un suffixe "_canBeNull". C'est moins dangereux que d'espérer que l'utilisateur de la fonction va vérifier dans la documentation si la fonction fait partie des rares fonctions à retourner une référence qui peut être nulle. On peut aussi utiliser le suffixe "_canBeNull" dans des noms de paramètre.

    A part ça, dans Java, comme l'absence de type "référence forcément non nulle" est une source d'erreurs, il existe des annotations @Nullable et @NotNull. Mais il existe plusieurs implémentations de ces annotations, aucune n'étant l'implémentation standard.
    Plus d'infos ici : https://stackoverflow.com/questions/...n-should-i-use.

    En C++, par contre, on a la chance d'avoir la distinction entre pointeurs et références. Les pointeurs peuvent être nuls, pas les références.

  11. #11
    Membre à l'essai
    Homme Profil pro
    Formateur en informatique
    Inscrit en
    juillet 2017
    Messages
    8
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Loire Atlantique (Pays de la Loire)

    Informations professionnelles :
    Activité : Formateur en informatique

    Informations forums :
    Inscription : juillet 2017
    Messages : 8
    Points : 12
    Points
    12

    Par défaut Melange des genres

    Bonjour tout le monde

    En lisant le sujet, c'est exactement ce que je me suis dit : la personne mélange les différents niveaux de documentation.

    De plus, quand on est sur la documentation grâce aux commentaires de code, pour moi, il ne s'agit pas de documentation. Il s'agit de complément d'information pour des personnes qui relisent notre code.

    Mais pourquoi commenter ? Un commentaire n'est pas en soi important.
    Pourquoi ne pas créer des méthodes avec des noms clairs ? Pourquoi ne pas créer des classes avec des noms compréhensifs ?

    En fait coder, ça peut s'apparenter à créer un nouveau langage : si tu n'as pas le traducteur, il faut aider les autres personnes pour lire ce que tu as écris.

    En revenant sur la documentation technique, elle apporte un vrai plus, même si selon moi, c'est une erreur de faire tout le travail à la main. Il existe assez d'outils pour auto-générer une bonne partie de la documentation technique.

    La documentation fonctionnelle, si elle est bien organisée, en lien avec la documentation technique et le code (norme organisationnelle) va permettre à tout le monde de comprendre ce que l'on fait dans le code.

    A plus
    Evan

  12. #12
    Provisoirement toléré Avatar de MikeRowSoft
    Homme Profil pro
    sans profession
    Inscrit en
    avril 2013
    Messages
    1 195
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 39
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : sans profession

    Informations forums :
    Inscription : avril 2013
    Messages : 1 195
    Points : 8
    Points
    8

    Par défaut

    Citation Envoyé par Patrick Ruiz Voir le message
    Ce sous-ensemble est à mettre en cohabitation avec les conventions de nommage et de programmation structurée au sein du code. Ces dernières viendraient ainsi jouer leur rôle qui est – selon lui – de « documenter le comment et non le pourquoi ».
    [...]
    Partagez-vous l’avis de l’auteur sur la portée qu’il attribue à la notion de documentation en génie logiciel ?
    Presque tout a fait d'accord. Surtout quand il s'agit d'une "partie" de code à "intégré" dans un projet (ré-utilisabilité, "le comment"). Se code étant lui même un projet complet ayant sa propre documentation et interface de tests/validations ("le pourquoi").

    Bien sur "le comment" d'un algorithme (ponctuel dans une méthode), n'est pas "le comment" d'un "projet". Et encore moins justifier "un pourquoi" (la raison de) ...

  13. #13
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    575
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 575
    Points : 594
    Points
    594

    Par défaut

    Citation Envoyé par foetus Voir le message
    Il me semble que les tests unitaires peuvent faire office de documentation
    Les tests unitaires sont de la documentation, ils montrent des exemples d'usage des méthodes/fonctions… Mais lorsque tu utilise une lib, tu ne va pas aller te bouffer les tests unitaires pour savoir quelle borne est acceptée dans tes paramètres…

    Sérieux, si utiliser une fonction nécessite plus de temps qu'écrire le traitement nécessaire, tu préfère quoi ?

    Citation Envoyé par Pyramidev Voir le message
    Dans un langage comme le Java ou le C qui contient le type "référence qui peut être nulle" sans contenir le type "référence forcément non nulle", en pratique, la plupart des fonctions qui retournent des références retournent des références jamais nulles et la plupart des appels des fonctions sont pensés comme si les arguments n'étaient jamais nuls.
    Du coup, à mon avis, avec un tel langage, le mieux est d'adopter une convention […]
    Merci mais c'est se focaliser sur un cas particulier et simpliste. Pour ce cas, j'ai simplifié à ce que tout le monde comprends sans considérer le métier (et pour être honnête, ce cas a plus de 10 ans, je ne me souviens plus des détails). Il me semble que tu est intervenu sur le sujet commentaire du code, je reprends l'exemple d'un discutable
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    setAgeCapitaine(int age)
    où la proposition était d'utiliser un type signé pour éviter un âge négatif…*Mais l'âge d'un capitaine n'est pas juste positif et négatif…

    Après, les conventions ont le défaut d'être des conventions et d'être suivies…*ou pas. Lorsqu'elles sont bien implantées (cas de Python par exemple), ça marche. Mais une convention en vigueur dans une boite, c'est en soi beaucoup plus risqué.

    Si une fonction peut retourner une référence qui peut être nulle, il faut alors le signaler explicitement, par exemple avec un suffixe "_canBeNull". C'est moins dangereux que d'espérer que l'utilisateur de la fonction va vérifier dans la documentation si la fonction fait partie des rares fonctions à retourner une référence qui peut être nulle. On peut aussi utiliser le suffixe "_canBeNull" dans des noms de paramètre.
    Ce genre de suffixe/préfixe, clairement, non… Les noms de fonctions/variables doivent exprimer ce qu'elles font, pas comment et surtout pas représenter une implémentation technique.
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    getStrudents_canBeNull()
    est une aberration de lecture, mais surtout, est une fonction qui a fini par être exposée par la lib (ce n'était pas prévu à l'origine) et l'implémentation a changée, elle ne peut plus être Null… On fait quoi ? On garde un nom qui ne veut rien dire ou on change en informant les 8000 établissements de France qu'ils doivent modifier leurs outils qui utilisent notre lib ?

    Citation Envoyé par evanboissonnot Voir le message
    En lisant le sujet, c'est exactement ce que je me suis dit : la personne mélange les différents niveaux de documentation.
    En fait pas du tout, elle fait exactement la distinction entre les différents niveaux : nommage, commentaires, documentation type JavaDoc, PyDoc, DocBocks…, tutos… C'est bien écris dans son post mais très mal rapporté…

  14. #14
    Membre éprouvé
    Profil pro
    Inscrit en
    avril 2004
    Messages
    653
    Détails du profil
    Informations personnelles :
    Localisation : France, Essonne (Île de France)

    Informations forums :
    Inscription : avril 2004
    Messages : 653
    Points : 938
    Points
    938

    Par défaut

    Citation Envoyé par TiranusKBX Voir le message
    Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?
    Avec une doc utilisateur qui explique pourquoi sans dire comment et l'autre qui dit comment sans dire pourquoi, il te reste à jongler avec les deux plus le code pour t'y retrouver...
    Ce qui s'énonce clairement se conçoit bien ( Le hautbois)

  15. #15
    Membre confirmé
    Homme Profil pro
    Étudiant
    Inscrit en
    juin 2008
    Messages
    504
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : Étudiant

    Informations forums :
    Inscription : juin 2008
    Messages : 504
    Points : 625
    Points
    625

    Par défaut

    Citation Envoyé par martopioche Voir le message
    Merci mais c'est se focaliser sur un cas particulier et simpliste. Pour ce cas, j'ai simplifié à ce que tout le monde comprends sans considérer le métier (et pour être honnête, ce cas a plus de 10 ans, je ne me souviens plus des détails). Il me semble que tu est intervenu sur le sujet commentaire du code, je reprends l'exemple d'un discutable
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    setAgeCapitaine(int age)
    où la proposition était d'utiliser un type signé pour éviter un âge négatif…*Mais l'âge d'un capitaine n'est pas juste positif et négatif…
    Les puristes te diront qu'il faudrait implémenter une classe age. Ainsi on peut utiliser une panoplie de constructeurs. Ok, ça ne fait que déplacer le problème de l'âge négatif au constructeur Age(int yearsFromBirth); mais là on a un nom bien explicite (et on peut même interpréter un âge négatif comme le temps restant avant de naitre). Mais si l'on revient au problème initial, on peut affirmer, que si le code accepte un âge négatif si on ne le veut pas, c'est un bug, pas un manque de documentation.
    raphchar

  16. #16
    Membre éprouvé
    Profil pro
    Inscrit en
    avril 2004
    Messages
    653
    Détails du profil
    Informations personnelles :
    Localisation : France, Essonne (Île de France)

    Informations forums :
    Inscription : avril 2004
    Messages : 653
    Points : 938
    Points
    938

    Par défaut

    Citation Envoyé par raphchar Voir le message
    ... si le code accepte un âge négatif si on ne le veut pas, c'est un bug, pas un manque de documentation.
    Il n'y a pas très longtemps, les organismes financiers du monde entier ont du faire réécrire leurs logiciels pour prendre en compte les taux d'intérêts négatifs.
    Ce qui s'énonce clairement se conçoit bien ( Le hautbois)

  17. #17
    Provisoirement toléré Avatar de MikeRowSoft
    Homme Profil pro
    sans profession
    Inscrit en
    avril 2013
    Messages
    1 195
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 39
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : sans profession

    Informations forums :
    Inscription : avril 2013
    Messages : 1 195
    Points : 8
    Points
    8

    Par défaut

    Citation Envoyé par martopioche Voir le message
    [...]Mais lorsque tu utilise une lib, tu ne va pas aller te bouffer les tests unitaires pour savoir quelle borne est acceptée dans tes paramètres…[...]
    C'est vrai, le type de variable doit être commenté, surtout si cette "variable" est une "class" (instance).

  18. #18
    Expert confirmé
    Avatar de TiranusKBX
    Homme Profil pro
    Développeur C, C++, C#, Python, PHP, HTML, JS
    Inscrit en
    avril 2013
    Messages
    1 473
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 28
    Localisation : France, Seine et Marne (Île de France)

    Informations professionnelles :
    Activité : Développeur C, C++, C#, Python, PHP, HTML, JS
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : avril 2013
    Messages : 1 473
    Points : 4 924
    Points
    4 924
    Billets dans le blog
    6

    Par défaut

    Citation Envoyé par Nebulix Voir le message
    Citation Envoyé par TiranusKBX
    Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?
    Avec une doc utilisateur qui explique pourquoi sans dire comment et l'autre qui dit comment sans dire pourquoi, il te reste à jongler avec les deux plus le code pour t'y retrouver...
    Rien à voir!
    La documentation utilisateur c'est: comment utiliser le machin(ça rien à voir avec le code, c'est ne niveau 0 de description d'un programme)
    La documentation technique c'est: comment ça fonctionne et structuré
    merci de me mettre des quand mes messages sont pertinent, et pour les pas contents voici mon service client pour eux

    [Projet en cours] Strategy(nom provisoire) - Advance wars like
    cordova-plugin-file-hash Plugin cordova servant à obtenir le hash d'un fichier

  19. #19
    Membre régulier
    Inscrit en
    juillet 2007
    Messages
    60
    Détails du profil
    Informations forums :
    Inscription : juillet 2007
    Messages : 60
    Points : 94
    Points
    94

    Par défaut

    Pour moi ce n'est pas le code lui-même qui doit être commenté, celui-ci doit effectivement être lisible, ou alors pour donner une indication ponctuelle.
    (du style //j'ai utilisé la bibliothèque X par facilité, mais la Y serait plus adaptée pour telles raisons)

    MAIS : Un programme doit OBLIGATOIREMENT disposer d'une documentation de son API interne !
    Sans ça pour moi, c'est comme si on nous filait Java sans sa doc... Et on devrait deviner comment il fonctionne ... Quelle perte de temps

    Et là on se rends compte : Tiens il y a deux méthodes servant à faire le calcul de l'optimisation du temps de transport ... Tiens elles ne font pas les même calculs ... Tiens on l'aurait jamais vu sans une documentation de l'API ... Chacun tapant dans l'une ou dans l'autre grâce à une formidable et désespérée transmission orale.

    Perso, je ne suis tombé que dans des boîtes qui "n'avait pas le temps" de rédiger cette documentation. Et je leur en veux terriblement.
    Maintenant, soit c'est moi qui crée le logiciel (ça va paraître prétentieux) et je sais qu'elle est bien montée/documentée, soit je fais autre chose (chef de projet, management ...)

    mais en aucun cas je pourrais re-bosser pour une boîte qui me dit très orgueilleusement : Pas besoin de doc, de toutes façon ça bouge trop vite, on peut pas la maintenir, et tu peux lire le code !
    J’appelle ça
    1/ de l'ignorance des bonnes pratiques
    2/ De l'irrespect total envers les nouveaux venus
    3/ Du suicide à long terme

    Oui je suis remonté contre 80% des boîtes de devs Française, qui font de l'amateurisme à ce niveau.

  20. #20
    Membre confirmé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    575
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 575
    Points : 594
    Points
    594

    Par défaut

    Citation Envoyé par raphchar Voir le message
    Les puristes te diront qu'il faudrait implémenter une classe age.
    Puriste de quoi ? Parce que les puristes de la POO me diront surtout que si l'objet capitaine a une notion d'âge, celle-ci est définie dans le constructeur puisqu'un capitaine sans âge n'a pas de sens, donc il n'y a pas de méthode setAge.…

    Après, celui qui me propose une conception sur ces 3 lignes de commentaire pour me pondre un modèle qui vient complexifier l'ensemble sans apporter de solution, merci, je m'en passe. Car nous sommes d'accord que une classe Age est plus adaptée, mais il faut qu'elle puisse fournir l'âge par une AgeFactory elle même implémentant une AbstractAgeFactory pour prendre en compte les différents types de définition de l'âge. Ainsi, on peut l'injecter dans les CaptainFactory…

    Sérieux…*tu propose une classe qui encapsule un entier qui n'apporte aucun contrôle métier pour ce cas là… Oué…

    Citation Envoyé par MikeRowSoft Voir le message
    C'est vrai, le type de variable doit être commenté, surtout si cette "variable" est une "class" (instance).
    Pourquoi "surtout" si c'est une classe ? N'importe quelle donnée, non ?

Discussions similaires

  1. Réponses: 5
    Dernier message: 09/04/2010, 01h21
  2. Contribuez à la FAQ et aux CODES SOURCE XML
    Par Community Management dans le forum XML/XSL et SOAP
    Réponses: 12
    Dernier message: 21/04/2008, 20h52
  3. Réponses: 6
    Dernier message: 19/07/2007, 12h30
  4. Je cherche le code-source d'un interface de Windows
    Par Robert A. dans le forum Windows
    Réponses: 5
    Dernier message: 02/06/2003, 09h45
  5. [VB6] Code source pour modifier MsgBox
    Par khany dans le forum VB 6 et antérieur
    Réponses: 5
    Dernier message: 25/02/2003, 15h13

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo