Corriger, modifier, améliorer

Des erreurs pourraient exister dans le framework, de même que les fonctions proposées pourraient ne pas remplir à 100% le besoin ou carrément ne pas exister. Dans ce cas, comme vous avez accès aux sources, il vous est possible d’y effectuer des corrections et autres améliorations.

Deux questions se posent alors :

  1. Comment déboguer/exécuter pas à pas le framework
  2. Comment ne pas écraser mes corrections/amélioration lors d’une mise à jour de Betula ?

En informatique, on évite, le plus souvent possible, d’avoir plusieurs copies d’un élément ou d’une information; ceci pour ne pas se poser la question « quelle est la dernière version ». Selon cette bonne pratique, le framework proposé ici devra se mettre dans un seul répertoire auquel tous les projets utilisant Betula auront accès. Ceci répond déjà aux deux questions ci-dessus.

En premier, mettez les sources de Betula (téléchargé depuis ce site) dans un répertoire à part, par exemple C:\Mes Projets\Betula officiel.  En effet, le composant externe seul ne permettant pas l’exécution pas à pas à l’intérieur.

  • Du côté de Betula:
    • Ouvrez le projet Betula dans ce répertoire et créer des classes héritées. Par exemple, créez une classe cFichier_ (avec un souligné à la fin) et faites là hériter de cFichier, rien de plus pour l’instant.
  • Dans votre projet :
    • Ajoutez y Betula en faisant un clic droit sur la première ligne de votre arborescence projet (l’élément « Projet » lui-même) et choisissez l’option « Ajoutez des éléments dans le projet… »
    • Choisissez toutes les classes et collections de procédures nécessaires à votre projet depuis C:\Mes Projets\Betula offciel (celle de Betula et celle avec un souligné à la fin)
    • Une question vous est ensuite posée : Répondez [Référencer dans son emplacement d’origine] (sinon il va copier tous les éléments de Betula dans votre projet et vous vous retrouverez avec plusieurs copies d’un même fichier du framework, enfreignant ainsi la bonne pratique énoncée ci-dessus).
    • Créez ensuite, dans votre projet, deux perso-dossiers dans l’élément « Classes » de votre arborescence projet : « Betula officiel », « Mon Betula »
    • Dans le premier, mettez toutes les classes originales de Betula, dans le second, toutes vos classes héritées (avec un souligné)
    • Vous pouvez ensuite faire autant d’héritages et d’instanciations que vous voulez, mais uniquement à partir de vos classes héritées (avec un souligné).

Le framework va donc pouvoir s’exécuter en même temps que votre projet et vous pourrez exécuter pas à pas chaque ligne de code contenue dans Betula.

Si une correction est nécessaire

Pour les méthodes de classe

Vous devez recopier la méthode incriminée de Betula dans votre classe héritée (celle avec le souligné) avec le même nom de méthode. C’est là que la correction pourra se faire sans risque d’écrasement. Tout le code étant dans votre classe héritée, pas besoin d’appeler l’ancêtre (la méthode du même nom dans la classe de Betula).

Pour les procédures des collections

Créez une collection de procédures « COL_DebugBetula » et copiez la procédure incriminée dans cette collection (renommer là du même nom si WinDev ajoute ‘1’ à la fin). Dans votre code, appelez alors la fonction COL_DebugBetula.LaFonction au lien de, par exemple, COL_GUI.LaFonction.

Ensuite

Quand Betula est mis à jour : fermez votre projet et décompressez le fichier zip téléchargé depuis ce site dans C:\Mes Projets\Betula offciel. Rouvrez votre projet et recompilez.  Les fonctions pour lesquelles vous avez fait des corrections sont facilement identifiables dans le perso-dossier « Mon Betula » et vous pourrez les comparer avec la version la plus récente du framework.

Si une modification est nécessaire
Par exemples, vous faites un contrôle de plus, vous modifiez le texte d’erreur, vous ajoutez un paramètre.  Dans ce cas aussi, vous devez recopier le code provenant de la classe du framework dans votre classe héritée (celle avec le souligné) avec le même nom de méthode. Dans le cas des procédures, créez une nouvelle procédure dans une collection de votre projet (ex COL_GUI.MaFonction de Betula devient COL_MesProcédures.MaFonctionPlusMeilleureQuiTue).
Si vous souhaitez ajouter des méthodes ou des procédures
Il vous suffit juste de les mettre dans dans votre classe héritée (celle avec le souligné).

Quelques recommandations

Vous avez fait des corrections, des nouvelles classes ou fonctions ? Soumettez les à l’équipe de Betula via cette boite courriel afin d’envisager leur intégration dans le framework « maître ».

Règles d'intégration
L’équipe de Betula se fera un plaisir d’analyser toutes les propositions de corrections, modifications et évolutions pourvu qu’elles respectent les règles énoncées dans les prochains paragraphes.

Toute modification ou ajout dans Betula doit être dans la version courante du framework. En clair, inutile de soumettre du code en WinDev24 alors que le framework est toujours en WinDev 23. Cela ne s’applique pas aux corrections (si tant est qu’elles soient compatibles avec la version courante du framework).

Un test unitaire, prévoyant tous les cas, même (et surtout) les plus absurdes, doit être présent dans le projet soumis pour chacune des fonctions des collections de procédures.  Les classes seront, elles, testées via une fenêtre (une fenêtre par groupe de classes qui fonctionnent ensemble).

Les procédures et les classes seront testés dans tous les environnements qu’elles prétendent couvrir (ex : une modification dans la classe cEnregistrement fera l’objet de tests sur toutes les bases de données et toutes les plateformes).

Toute nouvelle version du framework qui sera publiée exécutera systématiquement l’ensemble de ces tests.  Il faut qu’ils soient tous positifs pour que la version soit publiée.

Si un test ne peut être fait (p.e. on a pas accès à l’environnement de test) ou est négatif, l’équipe de Betula décidera soit de revenir à une version fonctionnelle, soit, dans le cas de nouvelles fonctions, de la retirer du framework pour être soumise à la prochaine itération.

Règles de programmation

En premier, le framework est conçu pour fonctionner en UNICODE. Tout projet qui l’utilise tel quel doit donc être, aussi, en UNICODE. Pour cela, une attention particulière doit être faite sur les variables textes qui, parfois, doivent être déclarées explicitement en ANSI.

Langue

Les produits PC SOFT sont utilisés par une écrasante population francophone. Pour cela, le nom des fonctions, leurs paramètres, les variables et autres commentaires seront d’abord faits en français. Par exemple, éviter les « get » et « set » pour utiliser plutôt « lit » et « écrit ». Si une version anglaise du framework existe un jour, elle sera un « fork » du projet originale en français (idem pour les autres langues).

Les logiciels développés avec le framework peuvent être distribués à l’international. Pour cela, tous les messages doivent être traduits, au moins, en 2 langues : FR (France) et EN (Angleterre). Il est conseillé aussi de recopier le texte français dans la langue « canadien français » et le texte anglais dans « américain ».

Malgré que Google Translate et autres traducteurs en ligne sont très bons et vont encore s’améliorer, il est parfois nécessaire de faire de petites corrections. Merci d’y prêter attention.

Charte de programmation

Depuis de nombreuses versions, PCSOFT propose une charte de programmation « par défaut ». Elle est utilisée pour préfixer les variables et les objets mais aussi pour la coloration syntaxique.  Il est donc important d’utiliser cette charte car, non seulement, elle est disponible dans chaque installation des produits PCSOFT mais elle est aussi utilisée par une majorité de programmeurs. Le code reste ainsi universel et correctement affiché chez tout le monde.

Fonctions

Toutes les fonctions doivent également avoir un nom explicite, en français (voir chapitre langue ci-dessus), dans l’esprit de la nomenclature PCSOFT.  Le framework vise également la simplicité (en limitant le nombre de lettres au maximum). Exemples : Lit(), Écrit(), Sauve(), …

Tous les paramètres doivent également avoir un nom explicite sans commencer par p ou p_ . Chaque paramètre doit être typé.  Des exceptions peuvent exister mais il faut alors correctement les documenter (voir ci-dessous). Dans ce dernier cas, un paramètre sans type doit être préfixé par un x. Si des indirections sont faites sur les paramètres de la fonction, mentionner <utile> à côté des paramètres concernés pour éviter des avertissements lors de la compilation.

Si une fonction retourne une valeur, cette dernière doit également être typée sur la ligne de déclaration de la fonction.

Dans tous les cas, il est demandé de supprimer tous les commentaires ajoutés automatiquement par l’éditeur (tout simplement car cette mécanique comporte encore des bugs) et de commenter l’appel des fonctions selon le modèle suivant. Garder à l’esprit que seuls ces commentaires seront visibles dans le cas d’un composant externe (voir chapitre Distribution ci-dessus).

Définition : dire ici ce que fait ou pas la fonction

Paramètre : décrire ici l’utilité de chaque paramètre. Ne pas mentionner le type (qui doit déjà être mis dans la déclaration de la fonction) ni l’aspect obligatoire/facultatif également déduit de la définition de la fonction.

Valeur en sortie : la décrire de manière succincte, le type est déjà (habituellement) déclaré dans la fonction (voir ci-dessus).

Nommage des variables

Il est demandé de nommer les variables de manière explicite et de les typer selon leur contenu (permettant ainsi que le préfixe de la variable soit dans une couleur différente, voir charte de programmation ci-dessus). Évitez d’anciennes habitues telles que des variables i, n, buffer ou temp.  Des acronymes ou des diminutifs peuvent néanmoins être utilisés si ils sont connus de tous.  Par exemple : un POUR TOUT sur une table utilisera une variable nLigne, un numéro de facture utilisera nNumFacture.

Programmation objet et « actuelle »

Le framework est développé pour une utilisation « en objet ». Tout nouveau « module » doit également être programmé en POO. Un « module » peut être décrit comme un ensemble de fonctions qui peuvent être instanciés plusieurs fois tout en restant indépendants l’un de l’autre (en soi la définition d’une classe). Ce qui n’est pas lié à un « module » et est généraliste peut être mis dans les collections de procédures (ex : une conversion, des appels API Windows, …). Dans ce cas, utiliser ErreurDéclenche (avec une constante propre à la collection de procédures) pour remonter l’erreur au niveau du code appelant (s’inspirer des collections de procédures du framework).

Il est fortement conseillé d’utiliser les énumérations et combinaisons dans les paramètres de fonctions. Ceci facilite, non seulement, la programmation mais également l’appel des fonctions.

Des structures ou des objets peuvent aussi être employés quand il s’agit de passer en paramètre ou de recevoir un retour d’éléments complexes. Par contre, l’utilisation du . pour l’appel de leurs membres est à privilégier par rapport aux : (anciennes versions des éditeurs PCSOFT). Ex : monObjet.maMéthode au lieu de monObjet:maMéthode.

Plutôt que de multiplier les procédures et méthodes privées, l’utilisation des procédures internes doit être privilégiées si leur exécution n’est faite uniquement que depuis un seul code appelant. De même, il est important d’utiliser le concept des « propriétés » dans les classes pour remplacer les méthodes « getter » et « setter ».

Erreurs dans les formulaires

Les erreurs sont gérées par cErreur (voir cette page pour plus de détails).

Pour les erreurs qui doivent être affichées suite au code de validation d’un formulaire, ne pas afficher une boite de dialogue pour chaque erreur avec un RepriseSaisie sur le champ de saisie incriminé.  C’est mieux de les rassembler dans une variable pour les afficher une seule fois à l’utilisateur.  Pour cela, déclarez une chaine sErreur en début de code, remplir cette variable à chaque problème rencontré (sErreur+=[rc]+ »Le problème ») et au bout du code faire, par exemple : SI sErreur> » » ALORS Erreur(sErreur) SINON Renvoyer Vrai

Commentaires

Ce framework, on ne se le cache pas, est à destination des développeurs confirmés. Il n’est donc pas nécessaire de documenter « à tout va ». Nous comptons sur votre expertise pour identifier le code spécifique ou les astuces de programmation qui devront être expliqués.

Dans le cas où une limitation ou un bug du WLangage est détectée, le commentaire doit commencer par WxNN-AAAAMMJJ (ex : WD23-20181212 pour un problème identifié en WinDev23 le 12 décembre 2018)

Respect des standards internationaux
Toute fonction mise dans le framework doit respecter, en premier, les standards internationaux tels que ISO, le système international d’unité (qui en est une partie) et toute autre codification utilisée par le plus grand nombre.
Anonymisation
Tout objet ou code qui fera partie du framework sera anonymisé (lire « ne contiendra pas le nom du programmeur »).

En effet, ce projet open-source est, par définition, commun et partagé.  Le code étant disponible pour tous, chacun est libre de le modifier ou le corriger le cas échéant.  Il n’est donc pas souhaitable ni nécessaire de solliciter le programmeur de telle ou telle ligne de code en cas de question ou de problème.

Le forum est la place privilégiée pour partager ces questions. Peut être que le programmeur original y répondra ou peut être d’autres programmeurs, qu’importe en fait.  Le programmeur ne doit pas être vu comme un « responsable » mais, avant tout, comme un « contributeur ».

Quelques idées pour faire évoluer le framework

cBaseDeDonnées

  1. Ajouter les bases de données manquantes
  2. Permettre une connexion sur un répertoire de fichiers texte (ex : CSV, le répertoire est vu comme une BD tels HyperfileSQL et chaque fichier comme une table)
  3. Gestion des journaux

cEnregistrement

  1. Ajouter les bases de données manquantes
  2. Pouvoir gérer les fichiers des mémos sur le cloud (ex : Google Drive, DropBox, Microsoft OneDrive), …
  3. Gestion des blocages pour BD autre que HFSQL

COL_SourceODBC

  1. Ajouter les bases de données manquantes
  2. Documenter l’installation de chaque client

COL_Conversion

  1. Ajouter les unités de mesures manquantes

cHTTPServeur

  1. Pouvoir faire un serveur en HTTPS (sur lequel un navigateur peut faire un get)

cUtilisateur

  1. LoginLDAP() : permettre le login avec openLDAP

cAppParamètres

Pouvoir lire et écrire dans la base de registre et dans un fichier XML
cHTTP

Permettre la pause/la reprise d’un téléchargement
cFTP

  1. Permettre la pause/la reprise d’un téléchargement/téléversement
  2. Pouvoir donner une vitesse limite de téléchargement/téléversement

Interface utilisateur

  1. Ajouter un modèle de bouton OK et Annuler pour les formulaires
  2. Ajouter un superchamp pour la gestion des combos « modifiables à la volée »
  3. Ajouter un superchamp pour associer des documents externes dans un formulaire (avec possibilité de D&D sur le superchamp)
  4. Améliorer le superchamp de période (date début + date fin) en ajoutant les trimestres, les semestres et en faisant des sous-menus
  5. Superchamp pour l’ajout de pièce jointe (mémo) avec gestion du scanner