Vous avez acheté une licence HotDocs Developer, consulté les tutoriels et peut-être même suivi une formation en développement. Vous avez peut-être même lu des sujets qui vous intéressaient dans le fichier d'aide HotDocs ou parcouru le wiki HotDocs. Quoi qu'il en soit, vous êtes prêt à commencer à développer des applications de traitement HotDocs pour votre cabinet d'avocats ou votre entreprise.
Votre formation et vos lectures vous ont appris que les fonctionnalités principales de HotDocs s'articulent autour des composants, ou variables, que vous créez. (Un composant est tout élément que vous créez dans le fichier de composants associé à votre modèle de document [par exemple, des boîtes de dialogue, des variables, etc.]). Vous avez donc peut-être compris que les conventions de nommage que vous utilisez pour vos composants sont essentielles au bon fonctionnement et à la facilité d'entretien à long terme de vos applications HotDocs Process. Voici trois règles de nommage qui vous aideront à démarrer votre développement HotDocs.
Caractères interdits et CASE exilé
Les noms des composants doivent être relativement courts, mais significatifs. Un nom de composant peut comporter jusqu'à 50 caractères, y compris des lettres, des chiffres et certains symboles. Cependant, le premier caractère doit être une lettre. Chaque nom de composant doit être unique. Même si les composants sont de types différents, leurs noms ne peuvent pas être identiques.
Les caractères suivants ne peuvent être utilisés que s'ils sont précédés ou suivis immédiatement d'un caractère autre qu'un espace ; toutefois, leur utilisation est fortement déconseillée, compte tenu des modifications futures possibles apportées à HotDocs :
Vous ne pouvez pas utiliser les caractères suivants pour nommer vos composants :
Enfin, comme HotDocs utilise les MAJUSCULES pour ses modèles d'instructions et d'expressions, il est recommandé de ne PAS utiliser les majuscules pour nommer vos composants. Vous ne pouvez pas, par exemple, nommer un composant « ADD ATTY TO MC », car « ADD » est un mot d'instruction réservé dans HotDocs. Même si vous utilisez des majuscules pour les mots de vos noms de composants qui ne sont pas actuellement des modèles d'instructions ou d'expressions, vous ne pouvez jamais savoir avec certitude si HotDocs ajoutera ou non le mot que vous avez mis en majuscules à sa liste de mots réservés. Il est donc préférable d'utiliser « CamelCase », « Sentence case » ou « lowercase » plutôt que « UPPERCASE ».
Genre > Espèce/Général > Spécifique
Une pratique qui aide à organiser les composants dans le gestionnaire de composants et, de manière générale, à garder les éléments similaires les choses avec similaires est de nommer vos composants avec des mots qui commencent par être généraux, puis deviennent plus spécifiques. Par exemple, le mot racine dans le nom du composant pourrait être un mot clé principal pour un groupe ou un sujet (par exemple, ClientNom). Ce mot clé est souvent le premier mot du nom du composant, mais selon le type de composant, cela peut ne pas être le cas. Les mots suivants dans le nom de la variable doivent être de plus en plus spécifiques, décrivant d'abord un groupe secondaire, si nécessaire, puis des aspects plus spécifiques (par exemple, ClientDescriptionLégalePropriétéImmobilière). En général, la meilleure pratique consiste à éviter autant que possible d'utiliser des articles et des prépositions. Si vous avez le choix entre « NomDuClient » et « NomClient », utilisez ce dernier.
Exemples
Ne gaspillez pas 50 caractères, vous ne le regretterez pas.
C'est ici que je risque de déclencher une guerre de mots. (Pour ceux qui ne connaissent pas ce terme, une guerre de mots éclate sur les forums de développement Internet lorsque les partisans de convictions opposées et profondément ancrées sur « leur façon » de coder se dénigrent mutuellement dans un fil de discussion [par exemple, les produits Microsoft contre les produits Apple].) Ce que je suggère ici peut sembler peu pratique pour les développeurs qui ont déjà automatisé de nombreux modèles de documents en utilisant une convention de nommage des composants différente, mais pour ceux qui débutent, cela vaut peut-être la peine d'être pris en considération : utilisez « CamelCase » ou « Title_Case_With_Underscores » pour nommer vos composants, comme je l'ai fait dans les exemples ci-dessus.
Traditionnellement, de nombreux développeurs de modèles ont utilisé la notation hongroise pour indiquer le type de composant (par exemple, TE pour Texte), et beaucoup ont conservé des espaces blancs (« espaces ») dans les noms des composants pour faciliter la lisibilité. Les arguments en faveur de l'utilisation de la notation hongroise ont perdu de leur pertinence depuis HotDocs 5, car les versions plus récentes de HotDocs permettent aux développeurs de modèles de visualiser les types de composants dans le gestionnaire de composants sous forme d'icônes ou de texte, et de les rechercher et les trier facilement. En ce qui concerne les espaces, le fait de les omettre dans les noms de composants permet au développeur de modèles de disposer de beaucoup plus d'emplacements parmi les 50 alloués pour remplir avec des caractères significatifs qui indiquent la fonction d'un composant. De plus, l'utilisation de noms de composants sans espaces (par exemple, « CamelCase ») est la norme par défaut pour le développement de modèles HotDocs (un sujet qui mériterait un article de blog à part entière). Le respect de cette convention permet à HotDocs de lire le document modèle et de convertir les noms de variables « sans espaces » en invites dans l'entretien sans les erreurs que vous pourriez rencontrer si la convention de nommage stricte était désactivée.
Enfin, il convient de noter qu'à mesure que HotDocs continue d'évoluer et de s'aligner sur d'autres technologies compatibles, il pourrait devenir nécessaire de demander aux utilisateurs de supprimer les espaces dans les noms de leurs composants. Si tel était le cas, HotDocs fournirait un moyen de convertir ces composants contenant des espaces, mais en n'utilisant pas d'espaces dès le départ, vous aurez une longueur d'avance sur les autres. En fin de compte, les scripts HotDocs est un langage de programmation, et la convention de nommage des composants doit donc être non seulement appropriée pour le développement de modèles HotDocs, mais également compatible avec les autres langages de programmation ou de script.
Bon développement !
Note de la rédaction : Ce billet a été publié à l'origine sur HotDocs.com. En juin 2024, Mitratech a acquis HotDocs, une plateforme avancée d'automatisation des documents. Le contenu a depuis été mis à jour pour inclure des informations alignées sur nos offres de produits, les changements de réglementation et la conformité.
