Blog // Exirel.me

Retrouvez tous les articles liés au tag Documentation via le flux rss dédié à ce tag.

Obsolescence de la documentation

Par Florian Strzelecki - 18:21 - 28.01.2017

Tags : Documentation, Lecture, Obsolète

Les déménagements ont ceci de formidable qu'ils permettent de regarder ses plus vieilles affaires oubliées, et de faire un choix : garder, ou jeter. N'ayant plus la place de tout garder, et n'étant pas spécialement attaché aux affaires du passé, j'ai tendance à jeter assez vite - sauf les livres, c'est beaucoup trop difficile avec les livres.

Il se trouve que j'ai eu ce choix difficile devant un carton de livres techniques. Garder ou jeter ? Et puis, j'ai lu les titres, j'ai relu quelques passages, et surtout, j'ai vérifié les dates de publication : de 2006 à 2011. Le choix a finalement été beaucoup plus facile que prévu.

La documentation n'est ni éternelle ni immuable, elle doit changer, évoluer, et s'adapter aux évolutions de son sujet (langage, framework, outil, etc.). Les livres papiers, malheureusement, ne peuvent pas faire évoluer leur contenu - pas sans une intervention physique, généralement plus destructrice que bénéfique si j'en crois mon expérience. Je rajoute d'ailleurs que les magazines techs ont exactement le même problème : à partir du moment où c'est imprimé sur du papier, il y a une date de péremption au dos.

Je ne nie pas l'intérêt historique ou d'archivage de tels documents, qui restent très intéressant pour voir l'évolution de notre univers informatique - c'est toujours un peu drôle de voir 300 pages sur jQuery ou PHP 4 - mais d'intérêt pratique au quotidien, pour apprendre et transmettre des savoirs.

Au final, concernant les livres, je n'en achète plus, ayant réalisé déjà il y a quelques temps qu'ils ne peuvent pas rester une source d'informations fiables suffisamment longtemps pour en justifier l'achat.

Et en ligne, me direz-vous ? La situation n'est pas toujours mieux : dans l'univers JavaScript, il m'est souvent difficile de trouver la bonne documentation. Parfois l'URL de la doc n'est plus la même entre deux versions (par exemple pour Webpack), ou bien la documentation ne précise pas quelle version du logiciel elle documente (pour Godot), ou pire encore la documentation d'une version précédente, toujours supportée, a été retirée et n'est plus consultable en ligne.

Maintenir une documentation n'est pas une tâche aisée, j'en conviens, mais je suis toujours aussi surpris de voir que nous avons si peu d'outils à notre disposition pour améliorer la situation...

Subtile compréhension de listes

Par Florian Strzelecki - 23:59 - 04.11.2014

Tags : Python, Documentation, Programmation, list-comprehension, generator expression

Si vous faites du python, un jour ou l'autre, vous tomberez sur ce genre de structure :

new_list = [int(x) for x in list_of_string_values]

Il s'agit de l'expression très connue appelée list-comprehension. Puissante et pratique, elle permet d'améliorer la lisibilité (dans certains cas), et offre quelques outils intéressants pour réduire la complexité des algorithmes.

Mais connaissez-vous les generator-expression ? Et les set et dict comprehension ?

Bon, tout n'est pas toujours disponible dans toutes les versions de python. Alors je vous préviens, moi, je parle de Python 3.4, version que j'utilise désormais au quotidien. La plupart des exemples et concepts peuvent être transposés, d'une façon ou d'une autre, en Python 2.7.

Python logging et log level

Par Florian Strzelecki - 23:59 - 03.11.2014

Tags : Python, Documentation, Programmation, logging

Dans le précédent article, je parlais de l'héritage des loggers, technique très pratique pour mutualiser des comportements ou au contraire de les séparer. Vous avez pu voir comment faire en sorte que deux loggers n'utilisent pas le même niveau de log ou pas les mêmes handlers.

Un point que je n'ai pas abordé (parmi tant d'autres) est la gestion du niveau de log : il existe deux configurations de niveau, puis à l'usage il suffit de choisir la bonne méthode pour le bon niveau de log désiré. Certes, j'ai utilisé le niveau de log des loggers, mais je n'ai pas vraiment utilisé la notion de log level du handler.

Commençons donc par un exemple simple, cette fois-ci avec un seul logger ayant deux handlers :

from logging import getLogger
from logging.config import dictConfig

if __name__ == '__main__':

    dictConfig({
        'version': 1,
        'handlers': {
            'console': {
                'level': 'INFO',
                'class': 'logging.StreamHandler',
            },
            'file': {
                'level': 'INFO',
                'class': 'logging.FileHandler',
                'filename': 'log.txt'
            }
        },
        'loggers': {
            'main': {
                'level': 'INFO',
                'handlers': ['console', 'file'],
            },
        }
    })

    main = getLogger('main')

    main.info('My message.')
    main.error('My error message.')

Ce qui donne comme résultat :

$ python log.py
My message.
My error message.

Et dans le fichier log.txt vous retrouverez exactement les même messages.

Python logging et héritage de loggers

Par Florian Strzelecki - 22:20 - 02.11.2014

Tags : Python, Documentation, Programmation, logging

Prenons un exemple simple, un fichier log.py qui va définir deux loggers : main et main.part. Ces loggers pourraient très bien être définis dans un package main et son sous-module part. Pour l'exemple, nous allons faire beaucoup plus simple :

from logging import getLogger
from logging.config import dictConfig

if __name__ == '__main__':

    dictConfig({
        'version': 1,
        'handlers': {
            'console': {
                'level': 'INFO',
                'class': 'logging.StreamHandler'
            }
        },
        'loggers': {
            'main': {
                'level': 'INFO',
                'handlers': ['console', ],
            }
        }
    })

    main = getLogger('main')
    part = getLogger('main.part')

    main.info('My message on the main logger.')
    part.info('And my second message on the main.part logger.')

Ici, il y a donc :

Si vous faites python log.py c'est ceci qui devrait s'afficher dans votre console :

$ python log.py
My message on the main logger.
And my second message on the main.part logger.

Sauf que si vous retirez la partie dictConfig de ce bout de code, plus rien ne s'affiche. Il y a donc bien quelque chose à regarder de ce côté là.

Introduction technique au format Epub

Par Florian Strzelecki - 22:10 - 22.04.2013

Tags : Documentation, Livre numérique, epub, Tutoriel, Vulgarisation

Il n'y a pas très longtemps sur Twitter, un petit débat autour du livre numérique et le jeu de rôle s'est tenu entre @stephanegallay, d'autres twittos, et moi-même. Il en est ressorti ceci : et si j'écrivais un article de vulgarisation sur la fabrication d'epub ?

Bon, comme le sujet mérite bien plus qu'un seul article, je vais donc en faire plusieurs - dont voici le premier - pour parler de ce format, et sur comment fabriquer un fichier epub dans les grandes lignes. Je vais le faire en deux grandes parties, la première très technique, et la seconde sera orienté vers un public curieux mais sans avoir de solides compétences techniques.

Et vous verrez que le format epub n'est pas si compliqué que ça, et qu'on peut obtenir un résultat tout à fait potable avec quelques bons outils (libres et gratuits) et un brin de méthode. Le plus dur dans un livre numérique, ce n'est pas le format : c'est d'écrire un bon livre !

Je ne parlerai cependant pas des DRM et de toutes ces saloperies qui viennent bousiller tout espoir d'avoir un format ouvert et interopérable entre les mains des utilisateurs.

Tu ne routeras point comme un cochon

Par Florian Strzelecki - 19:57 - 11.04.2012

Tags : Framework, Web, Documentation, Bonne pratique, PHP, loldev, Technique

Ces derniers jours, j'ai un problème avec les URLs. Plus spécifiquement, avec certaines URLs, qui sont gérées par certains mécanismes de "routage d'url" (et de réécriture d'url).

Il y a les bons routages et les mauvais routages.

Les bons routages d'URLs considèrent un format type (à base d'expressions régulières par exemple), et permettent d'associer une URL concrète à ce format, et d'en tirer une représentation à usage interne pour l'application. Les mauvais routages d'URLs considèrent un format type (à base d'expressions régulières par exemple), et permettent d'associer une URL concrète à ce format, et d'en tirer une représentation à usage interne pour l'application. Sauf que c'est un mauvais routages d'URL.

Trêve de blagues (et faisons plutôt la paix) (...) (ok j'arrête) voici le vrai problème que j'ai en ce moment : lorsque / et /home/default produisent exactement le même résultat, c'est à dire, pointent finalement sur la même "ressource". Autant c'est bien gentil de vouloir de jolies urls, et d'avoir des mécanismes simples pour gérer automatiquement un tas de cas, mais ce n'est quand même pas très RESTFull au final (je hais la duplication de contenu).

Car il s'agit bien d'un problème de "comment", et pas de "quoi" : réécrire des URLs à usage interne, et adapter le routage en conséquence, c'est tout à fait normal - ce n'est pas sale. Mais autant le faire bien, s'il vous plait. Ce problème n'est malheureusement que rarement traité, même si lors de mes recherches, j'ai été agréable surpris par les documentations de Symfony 2 et CakePHP.

Faisons un petit tour d'horizon de ce que nous proposent certains frameworks "à la mode" du monde PHP, puisque c'est majoritairement chez eux que j'ai rencontré ce problème, que chaque développeur devrait connaître et savoir gérer. Je veux dire, en commençant par reconnaître le problème quand ils l'ont devant leurs yeux.

Zend Framework

Allez, on commence avec du lourd, du sale qui tache : ce bon vieux Zend Framework. Après toutes ces années, je ne sais pas pourquoi je dis encore "ce bon", parce que je le trouve tout sauf bon, et même si ce n'est pas le sujet, encore une fois, ce framework montre des faiblesses de conception.

Dans sa documentation concernant le système de routage d'URL, vous pouvez tomber sur Zend Framework: Default Routes, section qui vous explique ceci :

Zend_Controller_Router_Rewrite comes preconfigured with a default route, which will match URIs in the shape of controller/action.

Ah, donc non seulement c'est le routeur par défaut, mais en plus il a pile le comportement qu'on ne veut pas avoir. Heureusement qu'à la fin de cette section il est ajouté qu'on peut supprimer cette route par défaut... bien que, par expérience, les résultats sont plutôt hasardeux (du genre vraiment, et pénible avec ça).

Cela dit, ce n'est pas encore terminé, sur la partie Dispatcher vous pouvez lire ceci :

If any of the module, controller, or action are not found, it will use default values for them.

Et pour revenir sur mes expériences : oui, ça peut devenir un problème, puisque le mécanisme qui utilise les routes d'URLs a déjà sa façon de voir les choses, et ce n'est pas toujours à votre avantage. Rien que d'y penser... non, je n'ai pas envie d'y penser.

CakePHP : presque !

Je ne connais pas bien CakePHP, et de ce que j'en ai lu, ce n'est pas trop mal - mais bon, mon avis ne vaut pas grand chose, testez plutôt vous-même. Que nous dit la documentation de CakePHP : Default Routing ?

You can access an action directly via the URL by putting its name in the request.

Brrr... ok, la même chose que pour Zend-Framework (mais avec une documentation plus sympa cela dit), ce qui n'est pas vraiment une bonne chose. D'autant que la suite n'est pas mieux, puisqu'on retrouve même des conseils sur comment faire de mauvaises choses automatiquement :

The keys of the array should be named after the route elements in the URL, or the default elements: :controller, :action, and :plugin. The values in the array are the default values for those keys.

Erm... je reviens, je vais boire une litre ou deux de ice-tea, pour me calmer. Ah moins que... CakePHP : Disabling the default routes : en voilà deux paragraphes intéressants !

Dommage qu'ils ne prennent pas beaucoup de place, mais ils ont le mérite d'être là. Je retiens plus particulièrement ceci, qu'il faudrait peut-être mettre en gras, en gros, avec des néons et des balises <blink></blink> tout autour (non, je déconne, les néons c'est en trop) :

If you have fully customized all your routes, and want to avoid any possible duplicate content penalties from search engines [...]

Bon, d'accord, la raison mise en avant, c'est pour faire plaisir aux moteurs de recherches : en attendant, c'est déjà une mise en garde sur les dangers d'un routage un peu trop permissif et automatique. Un bon point, au moins (et puis la doc a vraiment une jolie tête).

Symfony : le 1, et puis le 2 ensuite

J'ai connu une version de la branche 1.x de Symfony, et si le framework ne m'a pas marqué plus que ça, je me souviens très bien de son système de routes, qui est relativement facile à configurer (notez que je ne parle jamais de performance ici). Cette fois je peux nuancer plus facilement mon discours.

Tout d'abord, il est parfaitement possible de se passer d'une route par défaut avec Symfony 1.x, et je le conseille même vivement. Le soucis, c'est que la documentation section 9 ne précise pas forcément très bien cet aspect là. Je reprends cet exemple de code fourni :

# generic rules
# please, remove them by adding more specific rules
default_index:
  url:   /:module
  param: { action: index }
default:
   url:   /:module/:action/*

Alors, oui, il y a un commentaire, mais c'est à peu près la seule remarque sur le sujet, et j'ai vu bien des développeurs l'ignorer complètement, l'oubliant, et reléguant cette ligne au fin fond des poubelles de l'histoire de leur framework favori.

D'ailleurs, un exemple de code un peu plus loin ne reprend déjà plus le commentaire, c'est dire... bref, là encore, Symfony rejoint la liste des frameworks qui permettent des choses bien crades, et qui en plus ne documentent pas bien la chose. Pas cool.

Symfony 2.x : de bonnes inspirations ?

N'ayant pas travaillé avec Symfony 2, j'ai du faire un peu plus de recherches, et j'ai été agréablement surpris par une documentation bien plus claire, et plus encore, par le système de routage.

Ce derniers ne propose pas (de manière documentée explicitement en tout cas), un mécanisme "générique" pour des urls qui peuvent correspondre automatiquement à une représentation interne (du genre :controller/:action comme dans la version 1.x). En cherchant un peu, j'ai trouvé que c'était tout à fait possible de mal faire les choses quand même, mais cela me semble moins grave, du fait d'une information qui n'est pas mise en avant du tout (là encore, contrairement à la version précédente).

Bref, bon point pour Symfony 2.x, qui propose un mécanisme de routage d'URLs relativement intelligent. Le point bonus : il propose même un système d’annotations, comme les décorateurs en Python, pour gérer ses URLs... un peu à la manière de Pyramid (un framework web minimaliste en python).

TL;DR: Tu ne routeras point comme un cochon

Vous l'aurez compris aux travers de ces exemples, je ne critique pas le principe de routage d'URLs en lui-même, mais seulement son implémentation, sa documentation, et les conseils fournis aux développeurs. Il y a dans la conception de ces outils une mauvaise compréhension des contraintes posées par les URLs et les bonnes pratiques. Les solutions apportées, bien que facile d'utilisation (et encore...), ne me semblent pas bien répondre aux problématiques posées, ou alors, seulement en partie, alors que toutes les parties sont importantes.

Je compare ces problèmes de conceptions à d'autres implémentations : celles de Django et de Pyramid, deux frameworks web en python. Ni l'un, ni l'autre, ne permettent simplement d'instaurer un tel mécanisme, mais proposent à la place une grande souplesse et une grande réutilisabilité.

Comme quoi, c'est un problème de conception, pas de fonctionnalité.

Sinon, une dernière blague pour la route ? Essayons de ne pas nous fâcher en si bon chemin !

Multi-Db avec Zend

Par Florian Strzelecki - 20:20 - 07.10.2011

Tags : loldev, Framework, Web, Zend Framework, Technique, Documentation, Programmation, SQL, PHP

Depuis que je travaille avec le Zend Framework (et ce n'est définitivement pas par passion ni envie), je ne passe pas une semaine sans avoir besoin d'aller voir dans le code source du framework pour comprendre ce qu'il fait, pourquoi, comment, et en quel honneur.

Et généralement, je me marre - enfin pas vraiment, mais faites comme si.

Cette semaine pour le #loldev du vendredi, c'est la documentation qui m'a donné l'info qui me manquait pour résoudre un problème qui n'est pas trivial à l'origine, mais qui devrait l'être avec un framework web digne de ce nom : comment gérer une application qui doit se connecter à différentes bases de données ?

En voilà une question intéressante... voici ma réponse.

Pages and pages of source code.

Image : Pages and pages of source code. - Neil Crosby (http://www.flickr.com/photos/thevoicewithin/) - Creative-Common By-NC-SA

Dédoublonner un tableau de tableau en php

Par Florian Strzelecki - 16:01 - 30.09.2011

Tags : Documentation, Programmation, PHP, Optimisation, loldev, Technique

Halala... le array_unique est définitivement une fonction trompeuse de php. Pourquoi ? Parce que son mode de dédoublonnage par défaut est SORT_STRING, et pas SORT_REGULAR. D'ailleurs, c'est d'autant plus un problème que ce fut le cas en PHP 5.2.9, puis retour arrière en PHP 5.2.10.

Note : documentation php de array_unique.

Le #loldev du vendredi nous vient donc de cette petite fonction. En voici l'exemple :

$res = array(
        array('id' => 2),
        array('id' => 3907),
        array('id' => 7814),
        array('id' => 2),
    );
$unique = array_unique($res);
var_dump($unique);

// Résultat :
// array(0 => array('id' => 2));

Ce qui est un problème, puisque le but, c'est seulement de virer la deuxième ligne, comme il a été fait dans l'exemple suivant :

$id = array();
foreach ($res as $idRes) {
    $id[] = $idRes['id'];
}
$id = array_values(array_unique($id));

Donc, oui, cela fonctionne et on obtient bien un tableau dédoublonné par la valeur de la clé 'id' de chaque tableau. Heureusement, il y a mieux aujourd'hui.

Ce code provient d'une application pré-5.2.9, où le flag "SORT..." n'existait tout simplement pas. Ce n'est donc pas la faute du pauvre développeur qui a dû trouver à l'époque une solution qui fonctionne ! Je n'aurais pas aimer être à sa place.

Car aujourd'hui, il suffit d'écrire ceci :

$res = array_unique($res, SORT_REGULAR);

Pour dédoublonner le tableau. Simple, efficace. Mais il aura fallu attendre PHP 5.2.9 pour pouvoir le faire !

Remarque : suite à des remarques, voici le pourquoi du comment SORT_STRING pose problème :

Par défaut array_unique transforme en string le contenu de chaque élément du tableau, donc (string) array(...) ça donne "Array". Donc il trouve que le tableau de tableau, c'est un array de 'Array', 'Array', 'Array', ... qui sont donc des éléments identiques, et ne retourne que le premier élément.

Logique, imparable, mais particulièrement pénible.

Svn Id dans un template

Par Florian Strzelecki - 13:11 - 19.08.2011

Tags : Web, Documentation, Programmation, Bonne pratique, Technique

Parfois j'y pense (et parfois j'oublie) : utiliser la propriété svn "svn:keywords" sur les fichiers, en utilisant tout particulièrement Id, et de temps en temps Author et Date (mais cela dépend du projet et des conventions de l'équipe).

Pour ceux qui ne connaissent pas, il s'agit d'une propriété que l'on peut mettre sur un fichier versionné avec svn (et pas un répertoire), de cette façon là :

svn propset svn:keywords "Id" fichier

Ensuite, dans le fichier, n'importe où (de préférence en entête du fichier, dans les commentaires), il suffit d'écrire ceci :

$Id$

Au commit du fichier, ceci sera remplacé par quelque chose comme :

$Id: Fichier 7814 2011-08-19 07:49:47Z Exirel $

En général, je pense à le mettre sur des fichiers de code, mais pratiquement jamais sur mes templates. Pourtant, c'est tout aussi pratique, surtout lorsque le template a plus d'importance que la façon de récupérer les données (ce qui est parfois une opération tout à fait triviale).

Du coup, au début de tous mes fichiers de template avec php, je mets ceci :

<?php /* @version $Id$ */ ?>

Avec smarty, je mets ceci :

{* @version $Id$ *}

Et avec django, je mets ceci :

{% comment %}
(...)
  - Version : $Id$
(...)
{% endcomment %}

Parfois, je me demande encore comment je peux oublier ça. Peut-être parce que je devrais l'automatiser, et plus le faire à la main ? Je dois être trop nostalgique de la ligne de commande...

perl: warning: Setting locale failed.

Par Florian Strzelecki - 18:25 - 03.07.2011

Tags : Documentation, Ordinateur, Charset, Technique

En plein dans une installation d'un serveur sous Ubuntu 10.04 LTS (32 bits), j'ai eu cette erreur, qui m'était déjà arrivée il y a bien longtemps sur une Ubuntu 9.04 :

perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
        LANGUAGE = (unset),
        LC_ALL = (unset),
        LANG = "fr_FR.UTF-8"
    are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").

Pour la résoudre, deux choses :

  1. Installer le paquet "language-pack-fr"
  2. Lancer la commande sudo dpkg-reconfigure locales

Et c'est tout, ni plus, ni moins. Faut juste y penser, et je me le note là autant pour le partager que pour m'en souvenir.

Edit : Pour info, l'install s'est très bien passée.

data.decode('UTF8')

Par Florian Strzelecki - 18:00 - 19.05.2011

Tags : Python, Documentation, Programmation, Bonne pratique, Technique

Gérer du texte est parfois (souvent) un véritable casse-tête quand des problèmes d'encodage de caractères pointent le bout de leur nez. Alors, pour avoir perdu bien trop de temps, je m'écris un article "marque-page" pour me rappeler que, bordel, voilà comment récupérer les données d'un fichier en UTF-8, les traiter avec Markdown, puis écrire le tout dans un fichier.

import markdown

f = open('fichier.txt', 'r')
data = f.read()
f.close()

html = markdown.markdown(data.decode('UTF8'))

h = open('fichier.html', 'w')
h.write(html.encode('UTF8'))
h.close()

L'idée, c'est de "décoder" la chaîne qui est à l'origine en UTF-8 vers de l'Unicode, puis la traiter comme je le souhaite (ici avec Markdown), puis de l'encoder en UTF-8 pour l'écrire dans un fichier. Voilà.

Simple, efficace, mais il faut y faire scrupuleusement attention, sous peine de se prendre ce genre d'erreur :

UnicodeEncodeError: 'ascii' codec can't encode character

Je mets à jour mon wordpress avec python-fabric.

Par Florian Strzelecki - 14:32 - 15.03.2011

Tags : Python, Documentation, Wordpress, Fabric, Technique

Comme tout bon informaticien qui se respecte, j'ai tendance à chercher le moyen le plus simple, le plus rapide, et le moins pénible pour moi, de faire les choses. Surtout lorsque ces choses sont des tâches répétitives, et/ou, facile à automatiser.

Parlons peu mais parlons bien, voici quel était mon problème :

Partant de ça, je suis allé piocher dans mes connaissances quels outils pourraient m'être utile. Et c'est ainsi que j'ai choisi Fabric : j'ai créé un petit script, je le partage aujourd'hui avec qui le souhaite, sans restriction d'usage.

Petit tour technique...

Documenter ses applications

Par Florian Strzelecki - 19:18 - 23.11.2009

Tags : Documentation, Programmation, Bonne pratique, Technique

Le pouvoir de la documentation est immense, et mésestimé par beaucoup trop de monde, parfois même par ceux à qui elle serait le plus utile, les développeurs.

Une documentation peut faire gagner du temps aux développeurs, mais c'est bien plus que ça. Le fait de documenter ses applications va au-delà du fait de gagner du temps, ou de gagner en compréhension : c'est un signe de qualité.

Pour ma part, je considère que documenter mes applications est un devoir, et un gage de qualité. Avec une bonne documentation, je montre que mon application a été pensée et imaginée dans le bon sens.

Une bonne documentation, évidement, car une mauvaise est peut-être pire que tout finalement.

La documentation de Django

Image : La documentation de Django