perlmodstyle - En ligne dans le cloud

PROGRAMME:

Nom

perlmodstyle - Guide de style des modules Perl

INTRODUCTION

Ce document tente de décrire les « meilleures pratiques » de la communauté Perl pour l'écriture de Perl.
modules. Il étend les recommandations trouvées dans perlstyle , qui doivent être prises en compte
lecture obligatoire avant de lire ce document.

Bien que ce document soit destiné à être utile à tous les auteurs de modules, il est particulièrement
destiné aux auteurs qui souhaitent publier leurs modules sur le CPAN.

L'accent est mis sur les éléments de style visibles par les utilisateurs d'un module, plutôt que sur
les parties qui ne sont vues que par les développeurs du module. Cependant, bon nombre des
les lignes directrices présentées dans ce document peuvent être extrapolées et appliquées avec succès à un
composants internes du module.

Ce document diffère de perlnewmod dans le sens où il s'agit d'un guide de style plutôt que d'un tutoriel.
sur la création de modules CPAN. Il fournit une liste de contrôle avec laquelle les modules peuvent être comparés
déterminer si elles sont conformes aux bonnes pratiques, sans nécessairement les décrire dans
détaillez comment y parvenir.

Tous les conseils contenus dans ce document ont été glanés lors de longues conversations
avec des auteurs et utilisateurs expérimentés du CPAN. Chaque conseil donné ici est le résultat
des erreurs précédentes. Ces informations sont là pour vous aider à éviter les mêmes erreurs et
le travail supplémentaire qui serait inévitablement nécessaire pour les réparer.

La première section de ce document fournit une liste de contrôle détaillée ; sections suivantes
fournir une discussion plus détaillée des éléments de la liste. La dernière section, "Commun
Pièges", décrit certaines des erreurs les plus courantes commises par les auteurs du CPAN.

RAPIDE AIDE-MÉMOIRE

Pour plus de détails sur chaque élément de cette liste de contrôle, voir ci-dessous.

Avant vous Commencer
· Ne réinventez pas la roue

· Corrigez, étendez ou sous-classez un module existant lorsque cela est possible

· Faites une chose et faites-la bien

· Choisissez un nom approprié

· Obtenez des commentaires avant de publier

Le API
· L'API doit être compréhensible par le programmeur moyen

· Des méthodes simples pour des tâches simples

· Fonctionnalité séparée de la sortie

· Dénomination cohérente des sous-programmes ou des méthodes

· Utilisez des paramètres nommés (un hachage ou un hashref) lorsqu'il y a plus de deux paramètres

Stabilité
· Assurez-vous que votre module fonctionne sous "use strict" et "-w"

· Les modules stables doivent maintenir une compatibilité ascendante

Documentation
· Rédiger la documentation dans POD

· Documenter l'objectif, la portée et les applications cibles

· Documentez chaque méthode ou sous-programme accessible publiquement, y compris les paramètres et le retour
valeurs

· Donnez des exemples d'utilisation dans votre documentation

· Fournissez un fichier README et peut-être également des notes de version, un journal des modifications, etc.

· Fournir des liens vers des informations complémentaires (URL, e-mail)

Libération considérations
· Spécifiez les pré-requis dans Makefile.PL ou Build.PL

· Spécifiez les exigences de la version Perl avec "use"

· Incluez des tests avec votre module

· Choisissez un schéma de numérotation de version raisonnable et cohérent (X.YY est le code Perl commun
schéma de numérotation des modules)

· Augmentez le numéro de version pour chaque modification, aussi petite soit-elle

· Packagez le module en utilisant "make dist"

· Choisissez une licence appropriée (GPL/Artistique est une bonne valeur par défaut)

AVANT DE VOUS La START L'ÉCRITURE A MODULE

Essayez de ne pas vous lancer tête baissée dans le développement de votre module sans y réfléchir un moment.
d'abord. Un peu de prévoyance peut vous épargner beaucoup d’efforts plus tard.

A it était fait avant?
Vous n’aurez peut-être même pas besoin d’écrire le module. Vérifiez si cela a déjà été fait en Perl,
et évitez de réinventer la roue à moins d’avoir une bonne raison.

Les bons endroits pour rechercher des modules préexistants incluenthttp://search.cpan.org/> et
et demandant sur "[email protected]"
(<http://lists.perl.org/list/module-authors.html>).

Si un module existant presque fait ce que vous voulez, pensez à écrire un patch, à écrire un
sous-classe, ou étendre le module existant plutôt que de le réécrire.

Do UN chose et do it ainsi que
Au risque d’énoncer une évidence, les modules se veulent modulaires. Un développeur Perl
devraient être capables d’utiliser des modules pour assembler les éléments constitutifs de leur application.
Cependant, il est important que les blocs aient la bonne forme et que le développeur
ne devraient pas avoir à utiliser un gros bloc alors qu'ils n'ont besoin que d'un petit.

Votre module doit avoir une portée clairement définie qui ne dépasse pas une seule phrase.
Votre module peut-il être décomposé en une famille de modules connexes ?

Mauvais exemple:

"FooBar.pm fournit une implémentation du protocole FOO et du standard BAR associé."

Bon exemple:

"Foo.pm fournit une implémentation du protocole FOO. Bar.pm implémente le BAR associé
protocole."

Cela signifie que si un développeur n'a besoin que d'un module pour le standard BAR, il ne doit pas
être obligé d'installer également des bibliothèques pour FOO.

Ce qui est in a prénom?
Assurez-vous de choisir dès le début un nom approprié pour votre module. Cela aidera les gens
trouvez et mémorisez votre module et rendez la programmation avec votre module plus intuitive.

Lorsque vous nommez votre module, tenez compte des éléments suivants :

· Soyez descriptif (c'est-à-dire décrit avec précision l'objectif du module).

· Être cohérent avec les modules existants.

· Refléter la fonctionnalité du module, pas la mise en œuvre.

· Évitez de créer une nouvelle hiérarchie de niveau supérieur, surtout si une hiérarchie appropriée existe déjà
existe sous lequel vous pourriez placer votre module.

Obtenez Réactions avant Publisher
Si vous n'avez jamais téléchargé de module sur CPAN auparavant (et même si vous l'avez fait), vous êtes
fortement encouragé à obtenir des commentaires sur PrePANhttp://prepan.org>. PrePAN est un site
dédié à discuter d'idées pour les modules CPAN avec d'autres développeurs Perl et constitue un excellent
ressource pour les développeurs Perl nouveaux (et expérimentés).

Vous devriez également essayer d'obtenir des commentaires de personnes qui connaissent déjà le module.
domaine d'application et le système de dénomination CPAN. Auteurs de modules similaires, ou modules
avec des noms similaires, peut être un bon point de départ, tout comme les sites communautaires comme Perl Monks
<http://www.perlmonks.org>.

CONCEPTION ET L'ÉCRITURE VOTRE MODULE

Considérations pour la conception et le codage des modules :

À OO or pas à OOO ?
Votre module peut être orienté objet (OO) ou non, ou il peut avoir les deux types d'interfaces
disponible. Il existe des avantages et des inconvénients pour chaque technique, dont il convient de tenir compte lorsque vous
concevez votre API.

In Perl Mieux Expertises (copyright 2004, publié par O'Reilly Media, Inc.), Damian Conway
fournit une liste de critères à utiliser pour décider si OO est la bonne solution pour votre problème :

· Le système en cours de conception est grand ou est susceptible de le devenir.

· Les données peuvent être agrégées dans des structures évidentes, surtout s'il y a un grand
quantité de données dans chaque agrégat.

· Les différents types d'agrégats de données forment une hiérarchie naturelle qui facilite l'utilisation
de l'hérédité et du polymorphisme.

· Vous disposez d'une donnée sur laquelle de nombreuses opérations différentes sont appliquées.

· Vous devez effectuer les mêmes opérations générales sur des types de données connexes, mais avec
légères variations en fonction du type spécifique de données auxquelles les opérations sont appliquées
à.

· Il est probable que vous deviez ajouter de nouveaux types de données plus tard.

· Les interactions typiques entre les éléments de données sont mieux représentées par les opérateurs.

· La mise en œuvre des composants individuels du système est susceptible de changer au cours
le temps.

· La conception du système est déjà orientée objet.

· Un grand nombre d'autres programmeurs utiliseront vos modules de code.

Réfléchissez bien pour savoir si OO est approprié pour votre module. Objet gratuit
L'orientation donne lieu à des API complexes qui sont difficiles à utiliser pour l'utilisateur moyen du module.
comprendre ou utiliser.

Conception votre API
Vos interfaces doivent être compréhensibles par un programmeur Perl moyen. Ce qui suit
les directives peuvent vous aider à juger si votre API est suffisamment simple :

Écrivez des routines simples pour faire des choses simples.
Il vaut mieux avoir de nombreuses routines simples que quelques routines monolithiques. Si ton
la routine change significativement son comportement en fonction de ses arguments, c'est le signe que
vous devriez avoir deux (ou plus) routines distinctes.

Séparez la fonctionnalité de la sortie.
Renvoyez vos résultats sous la forme la plus générique possible et permettez à l'utilisateur de choisir comment
pour les utiliser. La forme la plus générique possible est généralement une structure de données Perl qui
peut ensuite être utilisé pour générer un rapport texte, HTML, XML, une requête de base de données ou autre
sinon vos utilisateurs en ont besoin.

Si votre routine parcourt une sorte de liste (telle qu'une liste de fichiers, ou
enregistrements dans une base de données), vous pouvez envisager de fournir un rappel afin que les utilisateurs puissent
manipuler tour à tour chaque élément de la liste. File::Find en fournit un exemple
avec sa syntaxe "find(\&wanted, $dir)".

Fournissez des raccourcis et des valeurs par défaut judicieux.
N'exigez pas que chaque utilisateur du module franchisse les mêmes obstacles pour obtenir un résultat simple.
résultat. Vous pouvez toujours inclure des paramètres ou des routines facultatifs pour des tâches plus complexes ou
comportement atypique. Si la plupart de vos utilisateurs doivent en saisir quelques-uns presque identiques
lignes de code lorsqu'ils commencent à utiliser votre module, c'est un signe que vous auriez dû faire
ce comportement est un défaut. Un autre bon indicateur que vous devriez utiliser les valeurs par défaut est si
la plupart de vos utilisateurs appellent vos routines avec les mêmes arguments.

Conventions de nommage
Votre nom doit être cohérent. Par exemple, il vaut mieux avoir :

display_day();
display_week();
display_year();

que

display_day();
week_display();
show_year();

Cela s'applique également aux noms de méthodes, aux noms de paramètres et à tout ce qui est
visible pour l'utilisateur (et la plupart des choses qui ne le sont pas !)

Passage de paramètres
Utilisez des paramètres nommés. Il est plus facile d'utiliser un hachage comme celui-ci :

$obj->do_something(
nom => "wibble",
tapez => "texte",
taille => 1024,
);

... que d'avoir une longue liste de paramètres sans nom comme celui-ci :

$obj->do_something("wibble", "texte", 1024);

Même si la liste d'arguments peut fonctionner correctement pour un, deux ou même trois arguments, n'importe quel
plus d'arguments deviennent difficiles à retenir pour l'utilisateur du module, et difficiles à retenir pour le module
auteur à gérer. Si vous souhaitez ajouter un nouveau paramètre, vous devrez l'ajouter au
fin de la liste pour une compatibilité ascendante, et cela fera probablement votre liste
commande peu intuitive. De plus, si de nombreux éléments ne sont pas définis, vous pouvez voir ce qui suit
appels de méthode peu attrayants :

$obj->do_something(undef, undef, undef, undef, undef, 1024);

Fournissez des valeurs par défaut raisonnables pour les paramètres qui en possèdent. Ne faites pas en sorte que vos utilisateurs
spécifier des paramètres qui seront presque toujours les mêmes.

La question de savoir s'il faut transmettre les arguments dans un hachage ou un hashref est en grande partie une question
de style personnel.

L'utilisation de clés de hachage commençant par un trait d'union ("-name") ou entièrement en majuscules
("NOM") est une relique d'anciennes versions de Perl dans lesquelles des chaînes minuscules ordinaires
n'ont pas été gérés correctement par l'opérateur "=>". Alors que certains modules conservent les majuscules
ou des clés d'argumentation avec trait d'union pour des raisons historiques ou pour des raisons de style personnel,
la plupart des nouveaux modules devraient utiliser de simples touches minuscules. Quoi que vous choisissiez, soyez
cohérent!

Rigueur et avertissements
Votre module doit s'exécuter avec succès sous le pragma strict et doit s'exécuter sans
générer des avertissements. Votre module doit également gérer la vérification des contaminations, le cas échéant,
bien que cela puisse causer des difficultés dans de nombreux cas.

En arrière compatibilité
Les modules qui sont "stables" ne devraient pas rompre la compatibilité ascendante sans au moins un
longue phase de transition et changement majeur de numéro de version.

Erreur manipulation et messages
Lorsque votre module rencontre une erreur, il doit effectuer une ou plusieurs des actions suivantes :

· Renvoie une valeur non définie.

· définissez $Module::errstr ou similaire ("errstr" est un nom commun utilisé par DBI et d'autres
modules populaires ; si vous choisissez autre chose, assurez-vous de le documenter clairement).

· "warn()" ou "carp()" un message à STDERR.

· "croak()" uniquement lorsque votre module ne sait absolument pas quoi faire. ("crever()"
est une meilleure version de "die()" à utiliser dans les modules, qui rapporte ses erreurs depuis
le point de vue de l’appelant. Voir Carp pour plus de détails sur "croak()", "carp()" et autres
routines utiles.)

· Comme alternative à ce qui précède, vous préférerez peut-être lancer des exceptions à l'aide de l'erreur
module.

La gestion des erreurs configurable peut être très utile à vos utilisateurs. Pensez à offrir un choix
de niveaux pour les messages d'avertissement et de débogage, une option pour envoyer des messages vers un fichier séparé, un
moyen de spécifier une routine de gestion des erreurs ou d’autres fonctionnalités similaires. Assurez-vous de tout mettre par défaut
ces options à l'usage le plus courant.

DOCUMENTATION VOTRE MODULE

POD
Votre module doit inclure une documentation destinée aux développeurs Perl. Vous devriez utiliser Perl
"plain old documentation" (POD) pour votre documentation technique générale, bien que vous puissiez
souhaitez rédiger de la documentation supplémentaire (livres blancs, tutoriels, etc.) dans un autre
format. Vous devez aborder les sujets suivants :

· Un synopsis des utilisations courantes du module

· Le but, la portée et les applications cibles de votre module

· Utilisation de chaque méthode ou sous-programme accessible au public, y compris les paramètres et
valeurs de retour

· Exemples d'utilisation

· Sources d'informations complémentaires

· Une adresse e-mail de contact pour l'auteur/mainteneur

Le niveau de détail dans la documentation du module Perl va généralement du moins détaillé au plus
détaillé. Votre section SYNOPSIS doit contenir un exemple minimal d'utilisation (peut-être comme
à peine une ligne de code ; ignorez les cas d'utilisation inhabituels ou tout ce qui n'est pas nécessaire à la plupart
utilisateurs); la DESCRIPTION doit décrire votre module en termes généraux, généralement dans un simple
quelques paragraphes ; plus de détails sur les routines ou les méthodes du module, de longs exemples de code ou
d’autres éléments approfondis devraient être donnés dans les sections suivantes.

Idéalement, quelqu'un qui connaît un peu votre module devrait pouvoir actualiser son
mémoire sans appuyer sur "page suivante". Au fur et à mesure que votre lecteur continue à parcourir le document, il
devraient recevoir une quantité progressivement plus grande de connaissances.

L'ordre recommandé des sections dans la documentation du module Perl est :

· NOM

· RÉSUMÉ

· DESCRIPTION

· Une ou plusieurs sections ou sous-sections donnant plus de détails sur les méthodes disponibles et
routines et toute autre information pertinente.

· BOGUES/MISE EN GARDE/etc

· AUTEUR

· VOIR ÉGALEMENT

· COPYRIGHT et LICENCE

Conservez votre documentation à proximité du code qu'elle documente (documentation "en ligne"). Inclure le POD
pour une méthode donnée juste au-dessus du sous-programme de cette méthode. Il est ainsi plus facile de conserver le
documentation à jour, et évite d'avoir à documenter chaque morceau de code deux fois (une fois par
POD et une fois dans les commentaires).

LISEZMOI, INSTALLER, libérer Remarques, changelogs
Votre module doit également inclure un fichier README décrivant le module et donnant des pointeurs vers
informations complémentaires (site Internet, email de l'auteur).

Un fichier INSTALL doit être inclus et doit contenir des instructions d'installation simples.
Lorsque vous utilisez ExtUtils::MakeMaker, ce sera généralement :

perl Makefile.PL
a prendre une
faire un test
make install

Lorsque vous utilisez Module::Build, ce sera généralement :

perl Build.PL
Perl Construire
perl Test de construction
perl Construire l'installation

Des notes de version ou des journaux de modifications doivent être produits pour chaque version de votre logiciel.
décrivant les modifications visibles par l'utilisateur apportées à votre module, en termes pertinents pour l'utilisateur.

Sauf si vous avez de bonnes raisons d'utiliser un autre format (par exemple, un format utilisé
au sein de votre entreprise), la convention est de nommer votre fichier changelog "Changes", et de
suivez le format simple décrit dans CPAN::Changes::Spec.

PRESSE CONSIDERATIONS

Version numérotage
Les numéros de version doivent indiquer au moins les versions majeures et mineures, et éventuellement les versions sous-mineures.
libère. Une version majeure est une version dans laquelle la plupart des fonctionnalités ont changé, ou dans
quelle nouvelle fonctionnalité majeure est ajoutée. Une version mineure est une version dans laquelle une petite quantité de
une fonctionnalité a été ajoutée ou modifiée. Les numéros de version sous-mineurs sont généralement utilisés pour
les modifications qui n'affectent pas les fonctionnalités, telles que les correctifs de documentation.

Le schéma de numérotation des versions CPAN le plus courant ressemble à ceci :

1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32

Un numéro de version CPAN correct est un nombre à virgule flottante avec au moins 2 chiffres après le
décimal. Vous pouvez tester s'il est conforme au CPAN en utilisant

perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'

Si vous souhaitez publier une version « bêta » ou « alpha » d'un module mais que vous ne souhaitez pas que CPAN.pm
indiquez-le comme le plus récent, utilisez un '_' après le numéro de version habituel suivi d'au moins 2
chiffres, par ex. 1.20_01. Si vous faites cela, l’expression suivante est recommandée :

notre $VERSION = "1.12_01" ; # donc la distribution CPAN aura
# bon nom de fichier
notre $XS_VERSION = $VERSION ; # nécessaire uniquement si vous avez du code XS
$VERSION = éval $VERSION; # donc "utiliser le module 0.002" ne vous avertira pas
# souligner

Avec cette astuce, MakeMaker ne lira que la première ligne et lira donc le trait de soulignement,
tandis que l'interpréteur Perl évaluera la $VERSION et convertira la chaîne en un
nombre. Les opérations ultérieures qui traitent $VERSION comme un nombre pourront alors le faire
sans provoquer d'avertissement indiquant que $VERSION n'est pas un nombre.

Ne publiez jamais quoi que ce soit (même un patch de documentation d'un seul mot) sans incrémenter le
nombre. Même un correctif de documentation d'un seul mot devrait entraîner un changement de version au moment
niveau sous-mineur.

Une fois choisi, il est important de s'en tenir à votre schéma de versions, sans en réduire le nombre.
de chiffres. En effet, les packageurs "en aval", tels que le système de ports FreeBSD,
interpréter les numéros de version de différentes manières. Si vous modifiez le nombre de chiffres dans votre
schéma de version, vous pouvez confondre ces systèmes afin qu'ils obtiennent les versions de votre module
d'ordre, ce qui est évidemment mauvais.

Conditions préalables
Les auteurs de modules doivent soigneusement réfléchir s'ils doivent s'appuyer sur d'autres modules et lesquels
modules sur lesquels s’appuyer.

Surtout, choisissez des modules aussi stables que possible. Dans l'ordre de préférence:

· Modules de base Perl

· Modules CPAN stables

· Modules CPAN instables

· Modules non disponibles au CPAN

Spécifiez les exigences de version pour les autres modules Perl dans les prérequis de votre
Makefile.PL ou Build.PL.

Assurez-vous de spécifier les exigences de version de Perl à la fois dans Makefile.PL ou Build.PL et avec
"exiger 5.6.1" ou similaire. Voir la section sur "utiliser la VERSION" de "require" dans perlfunc pour
détails.

USP,EP, BP
Tous les modules doivent être testés avant distribution (en utilisant "make disttest"), et les tests
devrait également être disponible pour les personnes installant les modules (en utilisant "make test"). Pour
Module::Build, vous utiliserez l'équivalent "make test" "perl Build test".

L'importance de ces tests est proportionnelle à la prétendue stabilité d'un module. UN
module qui prétend être stable ou qui espère être largement utilisé doit adhérer comme
strict un régime de test que possible.

Modules utiles pour vous aider à rédiger des tests (avec un impact minimal sur votre processus de développement ou
votre temps) incluent Test::Simple, Carp::Assert et Test::Inline. Pour les plus sophistiqués
suites de tests, il existe Test::More et Test::MockObject.

Emballage
Les modules doivent être empaquetés à l’aide de l’un des outils d’empaquetage standard. Actuellement vous avez
le choix entre ExtUtils::MakeMaker et Module::Build, plus indépendant de la plateforme,
permettant aux modules d’être installés de manière cohérente. Lors de l'utilisation de ExtUtils::MakeMaker,
vous pouvez utiliser "make dist" pour créer votre package. Des outils existent pour vous aider à construire votre
module dans un style convivial pour MakeMaker. Ceux-ci incluent ExtUtils :: ModuleMaker et h2xs. Voir
aussi perlnewmod.

Licence
Assurez-vous que votre module dispose d'une licence et que le texte intégral de celui-ci est inclus dans le
distribution (sauf s'il s'agit d'une distribution courante et que les termes de la licence ne vous obligent pas à le faire)
l'inclure).

Si vous ne savez pas quelle licence utiliser, double licence sous les licences GPL et Artistique
(le même que Perl lui-même) est une bonne idée. Voir perlgpl et perlartistic.

COMMUNE PIÈGES

Réinventer le roue
Il existe certains espaces de candidature qui sont déjà très, très bien desservis par le CPAN.
Un exemple est celui des systèmes de modèles, un autre est celui des modules de date et d'heure, et il existe de nombreux
plus. Bien que ce soit un rite de passage que d'écrire votre propre version de ces choses, s'il vous plaît
réfléchissez bien si le monde Perl a vraiment besoin de votre publication.

En essayant à do trop beaucoup
Votre module fera partie d'une boîte à outils de développeur. Il ne constituera pas, en soi, le
tout boîte à outils. Il est tentant d'ajouter des fonctionnalités supplémentaires jusqu'à ce que votre code soit monolithique
système plutôt qu’un ensemble de blocs de construction modulaires.

Inapproprié Documentation
Ne tombez pas dans le piège d’écrire pour le mauvais public. Votre public principal est un
développeur raisonnablement expérimenté avec au moins une compréhension modérée de votre module
domaine d'application, qui vient de télécharger votre module et souhaite commencer à l'utiliser comme
Aussi vite que possible.

Les didacticiels, la documentation destinée à l'utilisateur final, les documents de recherche, les FAQ, etc. ne sont pas appropriés dans un
la documentation principale du module. Si vous voulez vraiment les écrire, incluez-les comme sous-
documents tels que "My::Module::Tutorial" ou "My::Module::FAQ" et fournissez un lien dans le
VOIR AUSSI la section de la documentation principale.

Utilisez perlmodstyle en ligne en utilisant les services onworks.net