SPIP Blog
code.spip.net une ode au codeBonjour à toutes et tous.
Un nouveau site, si l’on peut dire, vient de naître dans la galaxie SPIP. Nouveau dans son nom et dans son fonctionnement, mais pas dans son objectif, puisqu’il est simplement le successeur de http://doc.spip.org/ qui n’était plus vraiment maintenu.
Ce site, code.spip.net, présente deux facettes, comme le faisait déjà l’ancien.
Autodoc
C’est une documentation exhaustive des fonctions du code source PHP de SPIP, qui s’appuie cette fois sur un logiciel tierce (phpDocumentor 2). Cette partie, nommée « Autodoc » est donc générée à partir des informations dites de « PHPDoc » ou « DocBlock » présentes au dessus des fonctions PHP. Notez déjà que toutes les fonctions de SPIP ne sont pas encore documentées au format PHPDoc, mais cela s’améliore, tranquillement au fil de l’eau.
Un bouton « Proposer une amélioration » permet aux visiteurs du site d’apporter leur contribution sur ces PHPDoc, sous chaque présentation d’une fonction. Les modifications, si elles sont acceptées par les webmestres, seront ainsi ajoutées au code source de la version en développement de SPIP.
Quelques difficultés ne sont pas encore résolues sur ce site, notamment pour ce qui concerne la présentation des pipelines. C’est un point auquel on doit encore réfléchir.
Enfin, cette partie du site ne peut être traduite.
APIs et Fonctionnements techniques
Cette deuxième partie, très peu remplie actuellement, vise à présenter des fonctionnements techniques internes à SPIP, ainsi que des fonctions d’API stables, avec plus de détails (et de rédaction) que dans l’Autodoc. Ces documentations sont elles-mêmes découpées en deux parties :
- les fonctions API qui sont un objet éditorial spécifique, s’incluant dans des rubriques ;
- les présentations de fonctionnements qui sont des articles.
Cela permet, sur les API notamment, d’avoir des champs spécifiques (pour leur historique par exemple). Ainsi http://code.spip.net/fr/apis/autoriser/autoriser peut afficher l’évolution de la fonction et d’autres informations.
Cette partie du site peut être traduite.
Archives de doc.spip.org
Tous les articles de doc.spip.org ont été intégrés dans une section archives de code.spip.net http://code.spip.net/fr/archives/ . La plupart d’entre eux serait à remettre au goût du jour.
Que faire maintenant ?
Plusieurs choses sont à faire, sur le rédactionnel et sur le fond technique.
Sur le rédactionnel, il y a donc des articles et des API présentes sur spip.net actuellement qui pourraient migrer sur ce site. Cela pourrait alors devenir une bonne base pour présenter l’architecture technique de SPIP et ses API ouvertes (du moins celles qui paraissent les plus évidentes ou consensuelles).
Sur le plan technique, la partie Autodoc doit être entièrement refaite (gasp !) pour passer de phpDocumentor 2.0a13 à 2.0b8 (à l’heure de ce texte) ce qui ne sera pas simple.
Messages
3 août 2013, 22:45, par esj
Salut Mathieu
C’est bien que tu veuilles reprendre ce problème de documentation, car c’est à mon avis la raison principale pour laquelle SPIP n’est pas utilisé autant qu’il le mérite (dit autrement : SPIP n’est pas sans défaut, mais d’autres CMS qui en ont de pires ont plus la côte car mieux documentés).
Cela dit je trouve dommage que tu évacues d’entrée la question de la traduction. Une des raisons qui font que SPIP est vu à tort comme un système fait par des amateurs est que les commentaires du code ne sont pas en anglais. L’idée d’avoir les commentaires sur un site dédié plutôt qu’uniquement dans le fichier contenant le code a justement comme intérêt potentiel de pouvoir présenter le code et ses commentaires dans une langue choisie par l’utilisateur. Un tel développement d’un outil multilingue de commentaires de code me paraît intéressant en soi.
Pour contourner le problème de la langue des commentaires, j’avais préconisé, comme on le rappelle ici, la solution de l’eXtreme Programming consistant à ne pas commenter en échange de l’écriture d’un code extrêmement clair. La clarté n’étant pas un concept universellement partagé, j’avais donné quelques indications de ce que j’entendais par là dans la section Régles de programmation de l’article de spipnet Etendre SPIP qui date de SPIP 1.9 mais que j’avais remis à jour pour SPIP 2.0 (et cet article était lui-même une mise à jour du très vieil article de spipnet Contribuer à SPIP datant de 2001). A ma connaissance, rien d’équivalent n’a été produit pour SPIP3 (même pas sur la taverne à Tonton. Pour moi ça reste quand même le problème numéro 1 : le meilleur commentaire n’arrivera jamais à convaincre un développeur de rentrer dans un code incohérent, voire franchement mal écrit.
5 août 2013, 11:44, par Marcimat
Salut Emmanuel,
Je pense que tu as effectivement raison. Il y a certainement un défaut de documentation mais qui est peut être plus du à un manque de visibilité, clarté de ce qui existe déjà qu’à une absence réelle de cette documentation. Même le code source de SPIP est déjà en partie commenté, mais est peu visible (d’où le passage progressif à du phpDoc qui permet une extraction plus facile).
Je te rejoins aussi sur le fait qu’un code lisible peut se passer de documentation. D’ailleurs le phpDoc alourdi à ce moment là une telle fonction. Mais il reste de nombreux cas où il est difficile de connaître le contexte d’utilisation d’une fonction en regardant celle-ci. Le code ne permet de découvrir qu’un fonctionnement, et qu’une partie même d’un fonctionnement d’ensemble.
Une des difficultés que je vois à documenter le code source a posteriori, c’est qu’il est plus difficile de décrire ce fonctionnement d’ensemble, et même parfois certaines fonctions non documentées me paraissent très absconses individuellement. Du coup, documenter une fonction permet de voir si le code réalise effectivement ce que l’on désire. C’est d’ailleurs une bonne partie de l’eXtrème Programming que de créer systématiquement des jeux de tests unitaires sur le code.
Concernant la traduction de la documentation à l’intérieur du code source, je pense que c’est totalement impossible sur un code qui continue d’évoluer. Ma première approche d’ailleurs tentait de mettre en base de données toutes les infos de fonctions et documentations, mais le suivi des évolutions est très complexe (fonction renommée, fonction déplacée dans un autre fichier, etc.) ce qui obligerait les éventuels traducteurs à réécrire très souvent ce qu’ils avaient déjà traduits. Après, peut être qu’une clé définie dans le phpdoc d’une fonction pourrait servir d’identifiant unique pour ça. C’est à creuser.
L’idée d’avoir le code commenté en anglais n’est pas idiote non plus, vu que le français est ce qui rebuterait de nombreux contributeurs internationaux (c’est du conditionnel, j’en doute un peu), ou du moins que l’anglais est actuellement la langue de l’informatique !
Cela dit inversement cela me rebuterait également d’avoir le code en anglais ; ce n’est pas une langue de communication facile à apprendre (c’est pareil pour le français cela dit). [[cf. http://fr.wikipedia.org/wiki/Rapport_Grin ].
En tout cas, je préfère avant tout me concentrer sur ce qu’on peut faire actuellement, c’est à dire,
– terminer la documentation phpDoc du code source de SPIP (il en reste pas mal encore). C’est ce qui alimente donc l’Autodoc.
– décrire les API et des fonctionnements généraux techniques de SPIP sur le site SPIP, et ça c’est traduisible.
8 août 2013, 22:17, par esj
Quand je disais de se passer des commentaires, je n’incluais pas dedans les lignes destinées à PHPDoc, car celles-ci sont en fait des informations qui comblent les lacunes de PHP, langage dans lequel on ne peut définir le type des arguments et des résultats. Et tu retombes sur ce que je dis toujours : s’il y a quelque chose à commenter c’est le contexte, pas le texte.
Mais dans cette histoire on tombe sur un autre problème : ces lacunes de PHP n’en sont pas quand on écrit juste un script ici ou là, mais elles sont rédhibitoires quand un système atteint une taille que SPIP a dépassé depuis longtemps. On ne peut pas faire du développement de cette taille sans des contrôleurs automatiques de type des argument et des résultats. Pour des raisons historiques, SPIP a légitimement commencé sa vie à l’aide de PHP, mais celui aurait dû être abandonné.
Plus précisément, c’est lorsque l’usage de JQuery a été introduit que ça devenait indispensable, car celui ci introduisait un langage de plus dans le système, ce qui l’a rendu difficilement maintenable pour l’équipe, et difficilement appréhendabte pour les nouveaux venus.. Il aurait fallu basculer sur un implémentation en C distribué sous forme de module Apache, et donner l’équivalent JavaScript des filtres PHP présents dans les squelettes. Ca n’a rien d’évident je reconnais, mais le modèle actuel ne me paraît clairement pas l’avenir.
12 août 2013, 21:07, par opl
@esj Un CMS sous forme de module Apache, ça fonctionne très bien sur des serveurs mutualisés, n’est-ce pas ? Sérieusement...
15 août 2013, 08:14, par esj
Je ne comprends pas cette remarque. PHP est un module Apache qui est accessible sur les serveurs mutualisés, où est le problème ?