#mylife je viens de commencer un nouveau boulot chez La Roue Verte, une entreprise de covoiturage sur Grenoble, qui met à disposition son outil gratuitement pour les particuliers et base son business model sur du SASS avec les entreprises.
Pourquoi je vous raconte ça ? Parce que lorsque l’on commence un nouveau travail, il faut « rentrer dans la base de code », autrement dit, se familiariser avec le produit. J’ai donc eu la proposition suivante : « On a pas de doc, et ça nous embête, or, quel meilleur moyen de rentrer dans le code que de la rédiger ? Si tu es capable de faire la doc sans faute, c’est que tu as compris comment ça marchait ! ».
Un traitement de texte ? C’est quoi ?
Aussitôt dit, aussitôt fait, me voici à devoir documenter une base de données PostgreSQL, le modèle de notre application. Aucune contrainte sur les outils à utiliser, il faut juste que le rendu final soit un PDF. La solution de facilitée aurait été d’ouvrir LibreOffice Writer et de prendre une à une chaque colonnes de chaque tables en la décrivant. Cela peut sembler fastidieux, mais de toute manière, je n’y échapperai pas. Non, ce qui m’ennuyait dans cette solution, c’était le maintien à jour des données. Si la doc aurait été à jour au moment de sa création, il y avait fort à parier que le fichier texte n’allait pas être modifié par les développeurs lorsqu’ils modifieraient le schéma de la base, que ce soit par oubli, par flemme ou par manque de temps. Or, dès que le document n’est potentiellement plus le reflet exact de la base, même si la différence entre les deux est mineure, il ne devient plus possible de s’y référer, on ne peut pas savoir ce qui est correct de ce qui n’est plus à jour. L’intégralité du document (et ma vingtaine d’heures passées à le rédiger) devient inutile. Une doc pas à jour équivaut à « pas de doc ».
La génération automatique à la rescousse
La solution pour avoir une documentation toujours à jour ? La générer directement depuis le schéma de la base de données. Un coup de DuckDuckGo, et je découvre Autodoc, un outil en ligne de commande à qui on donne simplement l’accès à la base de données, et qui nous extrait des fichiers au format HTML, Dot, Dia et DocBook XML. HTML ? Parfait pour moi ça. Facile à mettre en forme en deux coups de CSS, qui se transformera en une seconde en un PDF grâce au « Imprimer dans un fichier » de Firefox… Je lance la génération.
Toutes les tables sont là, les colonnes aussi, mais aussi les contraintes (clef primaire, clef étrangère, not null, valeur par défaut…) ou encore les fonctions triggers, des statistiques, bref, beaucoup de choses. Les graphiques .dot ne sont pas vraiment exploitables, mais pas grave, ce n’est pas ça qui m’intéresse. Après un coup de CSS pour rendre le résultat moins moche, j’ai maintenant une documentation qui se génère en une commande, et qui est donc toujours à jour par rapport au schéma de la base de données.
C’est une bonne nouvelle, mais les informations contenues dans ce HTML sont finalement assez faibles. Il n’y a rien de plus que ce que je pourrais lire dans le create.sql, certes, sous une forme un peu plus lisible, mais tout de même, ce qui est intéressant, c’est de dire à quoi correspondent chaque table et chaque colonne. Ici, je connais leur type et leurs contraintes, et je peux imaginer ce qu’elles font grâce à leur nom, mais tout de même, ce n’est pas cela que l’on appelle une documentation.
COMMENT ON, THE solution
Après quelques recherches supplémentaires, j’ai donc trouvé la solution idéale pour le moment : COMMENT, qui permet d’ajouter très facilement un commentaire à à peu près tout et n’importe quoi (table, column, constraint, index, database… la liste est longue, vous pouvez la consulter dans la doc). La syntaxe est ultra simple :
COMMENT ON TABLE user IS 'Contient les utilisateurs inscrits dans l''application.'; -- Ajoute un commentaire sur la table "user"
COMMENT ON TABLE user.name IS 'Le nom de l''utilisateur'; -- Ajoute un commentaire sur la colonne name de la table "user"
Un coup de génération, et les commentaires s’affichent dans le .html 🙂
Cerise sur le gâteau, postgresql_autodoc nous permet de choisir le template sur lequel il doit se baser pour génerer la doc. J’ai donc modifié ce fichier pour retirer tout ce qui était inutile, améliorer le design et lui demander d’interpreter le HTML dans les commentaires. Magnifique ! Grâce à des <span class="technique"> et un bout de JavaScript, nous voici maintenant capable de masquer ou afficher en un clic les parties techniques de la documentation, celles qu’on a pas besoin de montrer quand on présente la partie métier de l’application.
Bien sûr, cette solution n’évite pas le fait que si un commentaire n’est pas ajouté ou pas mis à jour lors de la modification du schéma, la doc ne sera pas exactement à jour. Mais comme elle se base sur le schéma pour être généré, on est absolument sûr que toutes les tables et colonnes sont là et avec le bon nom, ce qui est déjà nettement mieux qu’une doc non reliée à la base de données.
Voilà, la mauvaise nouvelle, c’est que la commande COMMENT est spécifique à PostgreSQL et n’est pas dans le standard SQL, mais de toute manière, Postgres est la meilleure DB non ?
English version below.
Pour rappel, on désigne par « fédération » l’échange des données entre les différentes instances de diaspora* (appelées pods). Il s’agit donc du protocole qui permet aux serveurs de communiquer entre eux.
Avec le travail en cours pour extraire le code s’occupant de la fédération du reste du code de diaspora (oui, ce code devrait devenir une gem à part et donc être utilisable par n’importe quel projet qui veut parler avec diaspora* !), il me semble qu’un petit article de vulgarisation sur la fédération n’est pas de trop. J’ai régulièrement des remarques sur différents points qui m’obligent à réexpliquer un peu comment tout ça marche, alors un joli article à la limite du technique mais compréhensible par tous, ça me semble la solution parfaite, je n’aurai plus qu’à donner ce petit lien… 😀
Alors, comment les serveurs de diaspora* communiquent-ils, pour réussir à faire qu’être inscrit sur n’importe lequel d’entre eux permet (presque) la même chose que si tout le monde était sur le même serveur ? (comment ça, presque, je vous entends dire ? Oui, il y a quelques cas où vous n’aurez pas le même résultat après avoir effectué la même action quand vous êtes sur deux pods différents. Ce billet a justement comme but de vous expliquer pourquoi). Read More
Un court billet pour vous faire part d’une astuce que j’ai découvert aujourd’hui et qui va immédiatement m’être indispensable.
Si vous avez un peu joué avec le langage du web, HTML, et notamment sa dernière version, la 5, vous vous êtes sans doute aperçu qu’Internet Explorer avant la version 9 ne connaissait pas les nouvelles balises (article, aside, footer, header, nav, section, time, toussa quoi). En fait, aucun ancien navigateur ne les connait, et c’est bien normal, puisque les navigateurs sont sortis avant la norme. Mais au contraire d’Opera, de Safari et de Firefox, qui, même s’ils ne connaissent pas les balises, les stylent correctement (c’est-à-dire leur applique correctement le CSS), Internet Explorer, lui, les ignore purement et simplement.
Read More
Que vous soyez sous Windows ou Mac OS et que vous ayez envie de découvrir un système d’exploitation Libre ou que vous soyez un Geek qui souhaite installer un Linux à quelqu’un qui ne connait pas, ce billet devrait vous intéresser. Voici mon expérience en matière de Linux pour débutant.
Ah, Linux. Vous en avez entendu parler mais vous ne savez pas ce que c’est ? Vous avez envie d’essayer mais peur d’être perdu à la fois ? Ou alors, vous êtes un bidouilleur et vous en avez marre d’être appelé 5 fois par mois pour réparer le pc de [la copine / la soeur / la maman / la tante / la grand mère] (barrez les mentions inutiles et passez au masculin si nécessaire). Rassurez-vous ! D’autres ont déjà fait les frais de cette situation et sont prêt à partager leur expérience avec vous.
Je l’avais décidé, j’allais faire passer mes parents sous GNU/Linux. Marre de toujours défragmenter / mettre à jour (antivirus / antispyware / logiciels / OS) / réparer les conneries. J’avais la solution comme Taratatach de leur mettre une Ubuntu sans plus d’explications et de les laisser se débrouiller (hein ? t’as pas exactement fait ça ? J’avais cru.). J’ai préféré y aller plus doucement. Voici comment j’ai procédé.
Read More
Un petit mot aujourd’hui pour parler de l’ami des développeurs et designers web : Internet Explorer. Vous n’êtes pas sans savoir que par son comportement souvent catastrophique, IE est une véritable plaie. En général, quand on développe un site web, on fait le site comme il faut, avec les technos qu’il faut, et une fois qu’il est fini, on passe une semaine à regarder tout ce qui ne marche pas avec IE et on met des hacks un peu partout pour avoir des rendus corrects.
Mais le web avance, et s’il était indispensable il y a encore quelques années de supporter IE6, ce temps est de plus en plus en révolu. Personnellement, selon les exigences des clients, je supporte IE8 (IE9 n’étant pas disponible sous XP), mais jamais en dessous. Pas de temps à perdre avec ces vieux navigateurs. Et lors des projets HTML5 / CSS3, tant pis pour le 8. Car l’avenir est là. Il faut aller de l’avant.
Seulement, les visiteurs ne comprennent pas lorsqu’ils arrivent sur un site web qui ne fonctionnent pas, et dans la majorité des cas, râlent contre le développeur, sans savoir qu’ils sont eux même à l’origine du problème. La solution : les en avertir. Plusieurs sites se sont lancés dans la promotion de bannière / ruban à mettre sur son site web pour inviter les visiteurs à télécharger un navigateur récent, comme ie6 no more.
- Bandeau disponible sur le site « IE6 no more »
Personnellement, je trouve ce bandeau trop intrusif. Le visiteur se demande un peu « de quoi je me mêle ». Il n’est de plus pas à jour. J’ai donc pensé à une imitation du bandeau utilisé par Internet Explorer pour afficher des messages à l’utilisateur. On va tromper le visiteur pour lui faire croire que c’est le navigateur lui même qui lui dit qu’il n’est pas à jour. Le visiteur sera ainsi plus à même de faire la mise à jour, d’autant plus qu’il n’y a pas de choix à faire, seulement un « mettre à jour ». Bon, d’accord, tromper le visiteur, c’est mal, mais bon, là, c’est pour son bien.
Voici donc la bannière que j’ai créé :
- Bannière pour mettre à jour IE en se faisant passer pour le navigateur
Et le code qui va avec :
<!-- Code par Flaburgan http://geexxx.fr sous licence CC-BY-NC-SA-->
<!--[if lt IE 9]>
<div style='position: absolute; top: 0px; left: 0px;
width: 100%; padding: 2px 12px;
background: #ffffe5; border-bottom: solid #6f6f63 1px;
color: black; font: small "Sans Serif";'>
<img src="http://geexxx.fr/wp-content/uploads/2012/03/warning.png" alt="warning" style="float: left; margin: 0px 5px 0px 0px; border: 0px;" />
<a href='#' onclick='javascript:this.parentNode.style.display="none"; return false;' style="float:right;" >
<img src="http://geexxx.fr/wp-content/uploads/2012/03/cross.png" alt="close" style="margin: 0px 20px 0px 0px; border: 0px;" />
</a>
Attention ! Votre version d'Internet Explorer est périmée. Cliquez <a href="https://www.mozilla.org/fr/firefox/new/" style="color:black">ici</a> pour mettre à jour votre navigateur.
</div>
<![endif]-->
Les images (le warning et la croix pour fermer) peuvent être téléchargées ci-dessous si vous ne voulez pas faire un lien vers ce site :
Vous pouvez bien sûr changer le texte du bandeau s’il ne vous convient pas, et le traduire si vos visiteurs parlent globalement une autre langue.
Et maintenant, le dernier mot qui va forcément partir en troll : le lien pour mettre à jour permet de télécharger Firefox. Avant que tout le monde ne hurle, quelques explications : Le but ici n’est pas simplement de se débarrasser d’IE6 mais bien d’avoir un navigateur récent qui permet donc d’avoir un support du HTML5 et CSS3. Microsoft a fait de nombreux efforts en ce sens avec IE9 et je les en félicite. Le problème, c’est qu’IE9 n’est disponible qu’à partir de Vista. Hors la majorité des personnes dont le navigateur n’est pas à jour sont sous XP. Il n’est donc pas possible que le lien de la bannière permette la mise à jour vers IE9, il fallait donc un autre navigateur que celui de Microsoft (encore une fois, je le répète, j’aurais mis IE9 avec plaisir s’il avait été disponible sous XP). IE écarté, le choix de Firefox est tout naturel, c’est le seul navigateur qui n’est pas possédé par une entreprise. De plus, il ne nécessite pas d’être administrateur de la machine pour être installé.
Je répète que ce bout de code est complètement libre, vous pouvez donc le modifier et linker vers la page de téléchargement d’IE8 si vous le souhaitez (je vous conseille alors de modifier le if lt IE9 (lt signifiant less than) pour mettre 8 à la place).
Allez, mettez ça sur tous vos sites web, qu’on puisse enfin profiter des jolies technologies aujourd’hui disponibles sans se prendre la tête pour des ancêtres !
Vous n’êtes pas sans savoir qu’aujourd’hui, 1er Mars, la nouvelle politique de confidentialité de Google entre en vigueur. Je vais présenter ici quelques extraits de ces nouvelles règles et expliquer brièvement en quoi elle pose problème pour les utilisateurs. En espérant que ce premier article vous sensibilisera sur cette problématique, d’autres suivront pour vous expliquer en détail pour chaque service de Google comment le substituer par une solution libre et respectueuse de votre vie privée.
Read More
J’ai récemment découvert Behat et comme je trouve le concept très intéressant, j’ai pensé que quelques informations intéresseraient peut-être nos lecteurs pendant mon initiation à cette nouvelle forme de tests unitaires.
Behat a été créé dans le cadre d’une méthode de développement agile « Behavior Driven Development », je vous recommande la lecture de l’article Wikipédia qui traite du BDD pour plus d’information car comme je ne connais bien le concept, je vais écrire des choses triviales à ce sujet.
L’idée de Behat, qui s’inspire de projets pour d’autres langages (comme Cucumber pour Ruby), est d’écrire des tests en langage naturel. Voici l’exemple de la documentation officielle de Behat (pardonnez le manque de coloration syntaxique, mais le langage n’est pas supporté dans le plugin WordPress) :
Feature: ls
In order to see the directory structure
As a UNIX user
I need to be able to list the current directory's contents
Scenario:
Given I am in a directory "test"
And I have a file named "foo"
And I have a file named "bar"
When I run "ls"
Then I should get:
"""
bar
foo
"""
C’est en voyant cet exemple sur Twitter que j’ai découvert Behat, intrigué par cette façon de faire, assez éloignée de la façon de tester avec des outils de type xUnit.
Je vous propose de créer une petite classe PHP et de la tester rapidement pour découvrir Behat.
Read More
Hoy hoy,
Comme on a du le faire pour notre canal, je me suis dis que ça serait intéressant de le partager, tout simplement.
Commençons par une explication sur ce qu’est IRC, au cas où vous ne sauriez pas encore. Plutôt que de réécrire une énième définition d’IRC, j’ai piqué celle de Wikipédia.
Internet Relay Chat ou IRC, (en français, « discussion relayée par Internet »), est un protocole de communication textuelle sur Internet. Il sert à la communication instantanée principalement sous la forme de discussions en groupe par l’intermédiaire des canaux de discussion, mais peut aussi être utilisé pour de la communication de un à un. Il peut par ailleurs être utilisé pour faire du transfert de fichier.
Je vous invite à consulter cet article si les aspects techniques vous intéressent, il y a aussi quelques détails sur les commandes etc.
Pour utiliser IRC, vous devez utiliser un client. Certains réseaux IRC (la plupart en fait) sont accessibles depuis un webchat. Par exemple pour le réseau Freenode, l’adresse est http://webchat.freenode.net/.
Le client le plus connu pour Windows est mIRC, pour Mac OSX je conseille vivement X-Chat-Aqua et enfin on me dit qu’Empathy fonctionne plutôt bien sur Linux.
Revenons à nos moutons, ou plutôt à notre canal IRC. Nous nous sommes installés sur irc.freenode.net et avons choisi le canal #geexxx.
Comment réserver votre propre canal IRC ? C’est très simple, il suffit de suivre le guide et de taper quelques commandes !
Read More