Dans votre carrière de développeur, vous avez fait des milliers de lignes de code et certaines vous ont parfois donné du fil à retordre. Vous avez, peut-être, parcouru les forums à la recherche de solutions et remercié au passage d’autres développeurs qui vous ont mis sur la bonne voie. Mais ça marche et vous êtes fier du résultat. Vous voudriez, à votre tour, partager le fruit de ce travail pour qu’il soit utile à d’autres mais vous ne savez ni où ni comment. Vous êtes à la bonne place !
Participer activement à Betula
La plupart des développeurs croisés sur les forums travaillent pour des entreprises, parfois des grosses. Ils n’hésitent pas à partager un bout de code s’ils pensent qu’il peut répondre au besoin d’un autre développeur qu’ils ne connaissent pas. Ces lignes de code n’ont aucune relation avec leur industrie et ne mettent en péril ni leur carrière, ni leur entreprise. C’est du code « généraliste ». C’est de cela dont se nourri Betula pour grandir !
A votre tour, repérez ces lignes de code « généralistes » dans vos développements actuels, ou plus anciens, et envoyez-les dans Betula !
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 « maître ».
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.
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 original 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é le fait 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.
Pour des raisons de compatibilité avec tous les produits et types de compilation, les fonctions ne peuvent avoir qu’une seule syntaxe.
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 s’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 peut être instancié plusieurs fois tout en restant indépendant des autres modules (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, un appel d’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 grandement la programmation.
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)
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
- Ajouter les bases de données manquantes
- 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)
- Gestion des journaux
- Ajouter les bases de données manquantes
- Pouvoir gérer les fichiers des mémos sur le cloud (ex : Google Drive, DropBox, Microsoft OneDrive), …
- Gestion des blocages pour BD autre que HFSQL
- Gestion du undo et redo
- Ajouter les bases de données manquantes
- Documenter l’installation de chaque client
- Ajouter les unités de mesures manquantes
- Pouvoir faire un serveur en HTTPS (sur lequel un navigateur peut faire un get)
- LoginLDAP() : permettre le login avec openLDAP
Pouvoir lire et écrire dans la base de registre et dans un fichier XML
Permettre la pause/la reprise d’un téléchargement
- Permettre la pause/la reprise d’un téléchargement/téléversement
- Pouvoir donner une vitesse limite de téléchargement/téléversement
- Ajouter un modèle de bouton OK et Annuler pour les formulaires
- Ajouter un superchamp pour la gestion des combos « modifiables à la volée »
- Ajouter un superchamp pour associer des documents externes dans un formulaire (avec possibilité de D&D sur le superchamp)
- Améliorer le superchamp de période (date début + date fin) en ajoutant les trimestres, les semestres et en faisant des sous-menus
- Superchamp pour l’ajout de pièce jointe (mémo) avec gestion du scanner