Developer Refactoring Meeting - Friday 3td June 2005
From ClaroDevel
Date : 03/06/2005 | les autre rencontres Présents: Christophe, Mathieu
Coding Rules
nomenclature des noms des variables de langue ( bloc ? p_p_ ? )
à completer pas Mla
TRUE ou true ? FALSE ou false ? NULL ou null ?
- en faveurs des majuscules :
- true, false, null sont des constantes. et nos codings rules disent "constantes en majuscules"
- les true false de javascripts doivent être en minuscule, on peut donc facilement les différenciers quand on a pas de coloration syntaxique.
- en faveurs des minuscules :
- par réflexe tout le monde mets des minuscules
- Ca semble normal pour tous les membres de l'équipe
- en observant les autres codes c la solution la plus courrante
Décision implicite prise : minuscule
Coding Suggestion
creation d'une fonction pour afficher une ressource : claro_disp_media (swf, mp3, ..., txt, ...)
idée de créer une fonction générique avec claro_disp_media(ressources, mimetype='auto');
qui permettrait d'offrir une interface uniformisée à l'affichage de n'importe quelle ressource et qui ferai sous-traiter le vrai travail à une série de clato_disp_spécialisée selon le mime/type
(ressources, mimetype='auto'); <- c moi qui lance ca maintenant
le comportement par défaut serait de proposer le téléchargement (un player local pourra encore faire le boulot)
Reste à voir ce qu'on a déjà parmis la liste des mimes/types. par exemple le mp3 de seb.
utilisation phpDoc dans les sources.
fixer les règles
Il faut cloturer les expériences de moosh et uniformiser un peu tout ca. ce qui se dessine/confirme pour le moment /** * description * -blankline- * @lestags */ les tags pourront être séparés par des lignes blanches pour aérer
Avant une fonction
les plus utiles
- * description
- * @param paramètres de la fonction. on doit d'accorde mais un truc du genre nom, type, description
- * @author firstname name <email> contact privilégié pour cette fonction
- * @return type et forme de ce qui est retourné
@param[eter] (object objecttype|type) [$varname] [description]
les entêtes et cartouche
par trop de similitude, j'ai carrément remplacé la cartouche par le header phpdoc.
/** * CLAROLINE * * this lib provide function to work on announcement data of a course * * DB Table structure: * --- * * id : announcement id * contenu : announcement content * temps : date of the announcement introduction / modification * title : optionnal title for an announcement * ordre : order of the announcement display * (the announcements are display in desc order) * * @version 1.7 $Revision: 1.3 $ * * @copyright (c) 2001-2005 Universite catholique de Louvain (UCL) * * @license http://www.gnu.org/copyleft/gpl.html (GPL) GENERAL PUBLIC LICENSE * * @package CLANN * * @author Claro Team <cvs@claroline.net> */ //---------------------------------------------------------------------- // CLAROLINE Version 1.6 //---------------------------------------------------------------------- // Copyright (c) 2001-2005 Universite catholique de Louvain (UCL) //---------------------------------------------------------------------- // This program is under the terms of the GENERAL PUBLIC LICENSE (GPL) // as published by the FREE SOFTWARE FOUNDATION. The GPL is available // through the world-wide-web at http://www.gnu.org/copyleft/gpl.html //---------------------------------------------------------------------- // Authors: see 'credits' file //----------------------------------------------------------------------
// Authors: see 'credits' file
devient
* @author Claro Team <cvs@claroline.net>
Le sens change parce que ce n'est plus un "contributor list" du fichier mais un "contact privilégié
// This program is under the terms of the GENERAL PUBLIC LICENSE (GPL) // as published by the FREE SOFTWARE FOUNDATION. The GPL is available // through the world-wide-web at http://www.gnu.org/copyleft/gpl.html
devient
* @license http://www.gnu.org/copyleft/gpl.html (GPL) GENERAL PUBLIC LICENSE
C'est un format imposé . url puis nom de la licence choisie
// Copyright (c) 2001-2005 Universite catholique de Louvain (UCL)
devient
* @copyright (c) 2001-2005 Universite catholique de Louvain (UCL)
et là les 2 sont vraiment identiques
// CLAROLINE Version 1.6
devient
/** * CLAROLINE * * @version 1.6 $Revision 1.21$
le CLAROLINE est isolé parce qu'il ne nomme pas la version et il est déplacé en haut du bloc parce qu'il est le top name du script
$Revision 1.21$ est ajouté parce que copié dans les doc de l'api (on ne le mettait plus parce que double emploi avec le $Id$ du top du fichier.
faire une page sur le wiki avec commentaire de script, librairie et fonctions
une fois qu'on aura fixé, moosh fera une page sur le wiki pour décrire ces choix
Génération d'une doc api régulière
une fois le processus de phpdocumentation bien mis en place et répendu nous pourront lancer une génération de documentation de l'api. Qui devrai s'ettofer avec la volonté de faire plus et mieux nos fonctions, classes et librairies
gestion des erreurs : claro_get_failure: expliquation, partout, ???
Hugues nous a préparé des focntions de gestion d'erreur et on en fait que trop peu usage.
1° il faudrait ajouter les déclancheur où il convient d'en mettre. 2° montrer comment utiliser les erreurs qu'y sont enregistrer par ces méthodes.
C'est en fait documenté dans dans la lib elle-même
Et l'utilisation faite par moosh n'est pas celle prévue.
get_lang(), _() and $_lang[''] : avantages, désavantages???
C'est donc la fontion qui a été choisie. reste son nom qui n'a pas encore convaincu tout le monde.
Plus l'apparition de get_block
Refactoring
nomage des var/const de path: établir l'existant (+ priorité: réparation de la confusion $rootWeb && $clarolineRepository )
à completer pas Mla et moosh note fred : quid utilisation de dirname(__FILE__)
- N'utiliser rootWeb que pour ce qui sera affiché hors des pages claroline
- create_user,
- lost_password
- enroll par un tiers
- annonces
- rss
Structuration des dossiers de claroline
Pas de redite
déplacer les fichiers de langues
Passer de lang/french/ à inc/lang/fr/ (ou inc/lang/fr/iso8859-1/ )(ou inc/lang/fr-iso8859-1/ )
Pour le débat sur l'iso en derrnière subdivision.
En fait l'idée sera d'avoir par langue deux transtypage des langues
- Le charset le plus courrant de la langue
- et l'utf-8.
L'important c'est le contenu, la conversion de l'un à l'autre est à notre portée, sans demander plus aux traducteurs
l'utilité : le charset courrant est le plus répandu l'utf-8 permettrai d'avoir quelque chose de plus propre quand on doit dans une même page mélanger des textes qui viennent au départ de langue dont le charset courrant n'est pas le même.
l'inconvénient c'est qu'on rajoute une subdivision. on doit connaitre le charset pour trouver les fichier de tradu alors que pour le moment c'est l'inverse. UTF-8 & mysql; UTF-8 et client
Il faut aussi se questionner sur les patois...
fr_BE fr_icampus ...
Interface: input text utiliser maxlength ( exemple : username size 40)
à completer pas Mla
factoriser les entêtes de tables de liste pour les tris
pour tous les tableau de donnée utilisan des <table> dans claroline
utiliser une fonction générique qui gère
- l'affichage,
- les colonnes triables,
- les colonnes non triables
- si nécéssaire le filtrage
Refactoring Librairie
Toute requete sql doit être dans une fonction (insert, delete, update, ...)
Outre l'idée des librairies clarifiant le code en mettant les micros fonctionnalités dans des fonctions de tâches, si toutes les interventions SQL sont isolées dans des fonctions, cela offre une solution de portage à une autre SGBD.
Chasse aux fonction redondante + inventaire des librairies (doublons, ...) + nommage des librairies
à completer par Mla
Liste des fonctions redondantes, similaires ou dupliquées
- renommage des librairies
- les librairies se terminent par lib.php et non lib.inc.php
- nous avons la claro_main.lib.php pour les fonctions globales à la plateforme. On pourrait imaginer avoir claro_user.lib.php, claro_course, claro_classes, ... de cette manière on pourra faire une distinction entre les libs de la plateforme et les librairies des outils de cours.
- Quid actuel je veux écrire un script pour la gestion des cours quels scripts ? add_course.lib.inc.php, course.lib.inc.php, course_utils.lib.php, ...
exemple de renommage
- add_course.lib.inc.php ---> claro_course.lib.php ou kernel/course.lib.php
- CLANN.lib.inc.php ---> announcements.lib.php ( -> dans le module )
- CLCAL.lib.inc.php --> agenda.lib.php ( -> dans le module )
- config.lib.inc.php --> config.lib.php ou ( kernel/user.lib.php )
- course.lib.inc.php --> claro_course.lib.php
- user.lib.inc.php --> user_info.lib.php ( -> dans le module )
- user.lib.php --> claro_user.lib.php ou kernel/user.lib.php
bannir les select *
- remplacer les * par la liste des champs réellement utilisés
- pour faciliter la tâche de renomage des champs labélisé en francais, il est demandé de mettre déjà l'alias en anglais et de coder l'appli avec les noms anglais. (ceci n'est pas possible avec les insert/update mais c'est déjà très bien avec les select
Attention pour les count() count(*) reste le plus performant.
utilisation de claro_sql_get_table_name() dans les fonctions
Tâche pleinement entamée par moosh, non finie, il faut vérifier qu'il n'y a pas d'oubli. cette fonction utilise le dbName suite a un petit soucis avec addcourse. mais pour préparer à son changement de signature pour qu'on lui passe non pas dbNameGlu mais $course_id on utilisera la forme
$tbl_c_names = claro_sql_get_course_tbl(claro_get_course_db_name_glued($course_id));
et les fonctions qui y font appel prendrons comme habituel dernier paramètre $course_id=NULL
function announcement_get_item_list($order='DESC', $course_id=NULL)
le null fait réagir claro_sql_get_course_tbl en lui faisant utiliser le cours "courant", ce qui est le comportement par défaut actuel.
la transition de
claro_sql_get_course_tbl(claro_get_course_db_name_glued($course_id))
vers
claro_sql_get_course_tbl($course_id)
se fera quand une solution fiable sera trouvée pour add_course. Cette partie du code sera transformée avec l'arrivée des plugins
l'utiilsation de
$tbl_c_names = claro_sql_get_course_tbl(claro_get_course_db_name_glued($course_id));
permettre de déjà préparer toutes les fonctions sans devoir attendre les plugin.
Ce nouveau paramètre dans les fonctions permettra d'utiliser le mpeme code pour les outils direct que pour les indirects comme, linker, backup, fillToolCourse, rssGen, ...
utilisation d'une libre d'arbres dans Claroline (il y a 3 arbres dans claroline : les catgérories,les classes et les travaux : idéalement on devrait se baser sur la même implémentation (pear?) pour les réaliser.
voir : [1] (http://satz.free.fr/blog/index.php?2005/01/25/71)
Refactoring Tools
Annonces :envoi de message aux utilisateurs : Pas d'archive, email only, interface non appréciée
http://www.claroline.net/forum/viewtopic.php?p=20471#20471
Chat : L'outil de chat pourrait être refait avec JPSPAN, SAJAX, SOAP ?
cela rendrait l'outil beaucoup plus convivial
(Quelques tests avec JPSPAN et SOAP ont déjà été réalisés par guim)
- Objectifs
- Proposer une version de l'outil de chat plus aboutie que l'outil actuel qui est trop sommaire - Garder des contraintes d'installation de la plateforme qui soient simples. - Ajouter ce qui manque le plus à cet outil : une liste des personnes connectées au chat.
JPSPAN et SOAP
- Avantages
- Convivialité et transparence du système pour l'utilisateur final, le chat se présente en une seule frame, sans rechargement intempestif de toute la page HTML, seule la zone de texte se met à jour toutes les 'x' secondes, sans que cela soit perceptible à l'utilisateur. - Ne nécessite aucune contrainte technique supplémentaire pour l'installation de la plateforme côté serveur, (pas de machine jave, serveur IRC,etc,... - Les fonctions onload() et onUnload() de Javascript permettent de réaliser une liste "Who is online" relativement fiable et simple à mettre en oeuvre, ce que l'outil actuel ne permet pas.
- Objections
- Problèmes de compatibilités avec les navigateurs plus anciens (et avec certains navigateurs récents), il faudrait probablement prévoir une version alternative pour les utilisateurs de NS4 et consort... - Javascript doit être activé côté client. - Cela n'améliore probalement pas le cout en performance côté serveur lorsque beaucoup d'utilisateurs sont connectés. (les test actuels sont toujours avec un fichier texte mis à jour et consulté de manière periodique)
Config : tout en tableau --> page sur le wiki, $_settings['']
Config#configurations_stock.E9es_dans_un_tableau
Config : refaire une classe à la place des fonctions de la lib (Tools+Install+Upgrade)
à completer pas Mla & moosh
Config : claro_unquote_gpc()
à completer pas Mla
Utilisation Pear
Compat: expliquation modulo, mkdir, ...
PHP_Compat (http://pear.php.net/package/PHP_Compat)
Quickform
exemple HTML_QuickForm (http://pear.php.net/package/HTML_QuickForm)
http upload
Refactoring Upload: mieux gérer l'upload des fichiers et les erreurs (utiliser la lib pear) voir Direction PHP HTTP_Upload (http://pear.php.net/package/HTTP_Upload)
zip & tar.gz
--> Vincent Blavet devel de PCLZIP est le devel du package PEAR Archive_Tar (http://pear.php.net/package/Archive_Tar) Archive_Zip (http://pear.php.net/package/Archive_Zip)
<mla> il a juste envoyé des classes existantes pour dézipper et zipper <Moosh_> classes existantes <- faites par lui ? <mla> je vais lui dire qu'on utilise pclzip et qu'il doit utiliser celle-ci <mla> je ne sais pas <Moosh_> en causant de ca hier avec lui j'ai vu http://pearadise.net/index.php/view/package/pear.php.net/HTTP_Download/ <Moosh_> Provides an interface to easily send hidden files or any arbitrary data to <Moosh_> HTTP clients. HTTP_Download can gain its data from variables, files or <Moosh_> stream resources. <Moosh_> ... - Delivery of on-the-fly generated archives through Archive_Tar and Archive_Zip <mla> oui <Moosh_> or on avait parlé de rempacer pcl_tip par une de celles là (ou File_archive) parce que c le même dev
Refactoring DB
le mono db
plan de réalisation : - !! Upgrade !! -Conception de la nouvelle DB -Modification de l'installeur -Modification de la homepage (si nécessaire), modification de course_hompage. -Nettoyage de Claro_init_global, Claro_init_local,etc... -Adaptation des outils de cours et de l'admin -Optimisation des index de la table -Optimisation des query et des (select *)
placer les group tool dans tool_list et ajouter Deux colonnes "groupes" & "cours" ou créér un "rel_group_tools"
à revoir complètement en fonction de "modules"
placer les valeurs de group_properties dans course. ou dans une table des propriétés.
Dans la table "group_propreties de chaque cours" ne contenant que 1 enregistrement on as des valeurs de config. même si leur application concerne les groupes, leur unicité par cours prouvent que ce sont des propriétés du cours.
ces valeurs devraient donc être dans la table course, dans un champs qui leur est dédié.
Cette solution pouvant effrayer dans la multiplication des champs dans la table course, l'autre solution évoquée est la table des propriétés dans chaque cours. (ou centrale avec un course_id)
cette table contient 2 champs
- nom de la propriété
- valeur de la propriété
utilisation de 2 connections mysql (lecture et écriture) pour permettre utilisation de mirroirs ( notion de redacteur et lecteur + plusieurs serveurs claroline pour les campus de plusieurs centaines d'utilisateurs )
noms de champ en anglais
établir une liste des champs qui restent en français et se décider sur leur nommage en anglais
Gregory Lannoy (stagiaire ecam) aborde ce point
uniformisation des noms de champs ( exemple: admin idUser et user_id dans les autres tables )
à completer pas Moosh
les noms des champs : * "faculté" devrait être un mot banni
noms de table en anglais
suppression des valeurs magique, utilisation d'enum
faire un benchmark de create course et trouver pourquoi il est très très lent
régler le problème du cid vs coursecode
- course.id ne sert à rien, il était là pour pma
- course.code c'est le vrai course_id. c'est lui l'unique utilisé dans les relations
- course.fakecode c'est le code affiché, public
- course.dbname c'est le nom de la base, il devrait être le même que course.code mais subit les règles de nommage de mysql (plus rigoureuse) et les préfixage de la config.
- course.directory c'est le nom du répertoire où le cours se trouve, il devrait être le même que course.code mais subit les règles de nommage du système de fichier (plus rigoureux) et les préfixages de la config.
Pour avoir plus de sens ces champs sont aliasés pour avoir des noms plus cohérents
- course.id -> pas de nom car ignoré
- course.code -> sysCode
- course.fakecode -> officialCode
- course.dbname dbName
- course.directory -> path
3 choses sont reprochées à ce fonctionnement.
course.id VS course.code
course.id est numérique et complètement inutilisé
course.code est utilisé dans les relations alors qu'il s'agit de texte (moins performant dans les relations sql)
Il faut
- soit supprimer course.id
- soit l'utiliser dans les autre table comme FK.
course.fakecode !unique
Il doit pouvoir ne pas l'être. C'est un choix de développement de départ. Toutefois, il semblerait tout à fait normal de proposer un champs supplémentaire qui permettrait de qualifier l'entrée pour distinguer 2 cours claroline ayant le même officialCode.
Il est à noter que fakecode est en soit une FK institutionnelle. Si un cours est donné 3 fois, pour l'institution il n'en reste pas moins identiques pour les 3 sessions. C'est bien là preuve que ce n'est donc pas le code qui doit démontrer la différence entre ses trois instances.
course.sysCode = course.fakeCode à la création mais plus après un éventuel renommage de fakeCode
C'est de loin ce qu'on me reproche le plus.
le professeur donne fake code à la création.
sysCode, dbName et directory ne peuvent pas changer (en tout cas surment pas sysCode et directory)
donc en ca de renommage, pas question de les changer.
Hors par soucis de s'y retrouver un peu, il avait été décidé que sysCode, dbName et directory auraient un nom ressemblant à officialCode.
le code de claroline permet de se passer de cette "ressemblance" (il y a un flag à passer à FALSE)
Toutefois, est-il raisonnable de se rendre la vie difficile par défaut pour TOUS les cours ou d'accepter que pour quelques-un les évidences ne sont pas ce qu'elles sont.
Notez que si un "champ" de distingo etait ajouté il pourrait aussi être ajouté au nom. Ca ne règle pas les cas de renommage mais bien ceux de cours multiple avec le même code.
Cela réduit encore fortement le nombre de pièges
Plugins
ToolName : centraliser le tableau des noms d'outils et le rendre dynamique pour les plugins
Renaud a déjà fait la centralisation via sa fonction dont il avait besoin pour le linker.
Cette fonction à été appliquée par Moosh partout où on avait copié collé le tableau.
Donc coté code c'est ok.
reste le problème du dynamisme. C'est à dire que si on ajoute un outil , pour le moment il faut encore aller manuellement modifier le code,pour ajouter le nom de cet outil dans la fonction.
La piste évoquée pour le dynamisme est d'utiliser la table des outils en db centrale en y ajoutant le nom de la variable langue qui contien le nom de cet outil (cela nécéssitera un adaptation de l'outil de détection des varaible langue pour le sdk de traduction mais selon mathieu c'est tout à fait réalisable
Si on a besoin de cette liste, on aura très prob
Sécurité + Portabilité
- éviter les fonctions interdites des hébergeurs: exec, system, ...
- étude : faire une liste à jour des fonctions interdites par hébergeur (free, nexen, ovh, ...) + droits mysql.
- safe_mode
- Gestion des droits sur les rep créés, uniformiser ça (cfr: problème chez OVH) + Permission + Portabilité: 0777 partout et pas d'umask
- Securité: Interdire les includes des fichiers externes (config php.ini)
- Refactoring + Sécurité: Accès aux documents via php
- Sécurité: utilisation de realpath : claro_realpath + doit être dans le rootSys
- Config + Portabilité: utiliser pclzip par défaut, valeur de config pour /usr/bin/unzip (prob avec les hébergeurs sous linux)
Suggestion
ajout d'un edit text zone dans inscription à la plateforme, à un cours et lostpassword
un nombre très important d'institution ayant installé claroline a personalisé ces pages. Il semble pertinant, utile et demandé d'y ajouter des zones d'éditions aux endroti qui semble le plus personnalisés chez les autres.
dans la 1.6 top et right text identique quelque soit le status d'auth
Suite à une demande sur le forum d'avoir une diff entre anonymous et auth user
En effet avant le texte d'introduction n'était visible que dans un des deux cas.
maintenant on le voit qu'on soit authentifié ou non.
La demande est de pouvoir avoir des textes différents selon qu'on soit connecté ou non
inscription avec clé plateforme et cours (on a reçu une contrib pour les cours)
utilisation des auth "claroline" "clarocrypt" et "claroclear"
--> explication=
Uniformisation du pager
application aux autres endroits existants que l'admin: - document tool- user tool Applicable à d'autres élements qu'une DB (moteur de recherche de aur, ...)
Refaire la création d'info user spécifique au cours, l'interface n'est pas claire du tout
Programmation: Faire des test unitaires (simpleTest) - exemples : claro_mkdir
langue english_devels
Une variable langue doit avoir un nom représentatif de ce qu'elle contiendra en anglais. Toutefois on ne pourra jamais garantir que ce soit l'anglais qu'il convenait de mettre.
- Le codeur ne peut attendre a chaque fois la validation d'un anglophone
- le traducteur ne va pas aller changer le nom des variables dans le code s'il estime que le contenu n'est pas parfait.
l'idée proposée est celle d'une "langue tampon" english_devel. Dans le système de langue elle serait vue comme un patois de l'anglais.
Celle-ci sera la "langue des noms de variables" désavantage : Il ne faudra juste pas que ca soit une excuse pour que le noms des variables avec un anglais "baclé"
Translation: uniformiser les variables de langues (il y en a trop)
dans les sql de creation et alter table, utiliser une variable pour le format des champs de relation *accessoire*
créer un outil qui permet de changer cette taille sur toute la DB *accessoire*
export csv des listes
add security event
(login logout, lost password, create course, create account, subscribe, unsbscribe, edit profile,...)
les pop-up d'aide ??? Une var langue des plusieurs pages html n'est pas facile à traduire
--> fichier .html ???
les pop-up d'aide pour les étudiants + l'outil de travaux est trop compliqué.
Lien Contact dans le footer
--> Page de contacts + texte zone
ClarolineProposals
- Claroline RFC0003 - Claroline Date/time format convention for function
- Claroline RFC0004 - Force namespace for Claroline functions
- Claroline RFC0005 - Hidden system files and folders
