Participer

Participer activement au projet

Comme tout framework, Betula va continuer à évoluer.  Se basant sur les principes de l’open-source, la version « maître » du framework reste sur un GDS de l’équipe originale et chacun peut en récupérer une copie ci-dessus pour la modifier à son goût sur son propre GDS.

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

Règles d'intégration
L’équipe originale se fera un plaisir d’analyser toutes les propositions de corrections, modifications et évolutions pourvu qu’elle respecte 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 originale 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