perlmodstyle - Online en la nube

PROGRAMA:

NOMBRE

perlmodstyle - guía de estilo del módulo Perl

INTRODUCCIÓN

Este documento intenta describir la "mejor práctica" de la comunidad de Perl para escribir Perl
módulos. Extiende las recomendaciones encontradas en perlstyle, que deben ser consideradas
lectura requerida antes de leer este documento.

Si bien este documento está destinado a ser útil para todos los autores de módulos, es particularmente
dirigido a autores que deseen publicar sus módulos en CPAN.

La atención se centra en los elementos de estilo que son visibles para los usuarios de un módulo, en lugar de
aquellas partes que solo ven los desarrolladores del módulo. Sin embargo, muchos de los
Las directrices presentadas en este documento se pueden extrapolar y aplicar con éxito a un
internos del módulo.

Este documento se diferencia de perlnewmod en que es más una guía de estilo que un tutorial.
sobre la creación de módulos CPAN. Proporciona una lista de verificación con la que se pueden comparar los módulos.
para determinar si se ajustan a las mejores prácticas, sin necesariamente describir en
detalle cómo lograr esto.

Todos los consejos contenidos en este documento se han extraído de extensas conversaciones
con autores y usuarios experimentados de CPAN. Cada consejo dado aquí es el resultado
de errores anteriores. Esta información está aquí para ayudarlo a evitar los mismos errores y
el trabajo extra que inevitablemente sería necesario para arreglarlos.

La primera sección de este documento proporciona una lista de verificación detallada; secciones posteriores
proporcione una discusión más detallada de los elementos de la lista. La sección final, "Común
Pitfalls ", describe algunos de los errores más comunes cometidos por los autores de CPAN.

RÁPIDO LISTA DE CONTROL

Para obtener más detalles sobre cada elemento de esta lista de verificación, consulte a continuación.

Antes usted comienzo
· No reinventes la rueda

· Parchear, ampliar o crear una subclase de un módulo existente cuando sea posible

· Haz una cosa y hazla bien

· Elija un nombre apropiado

· Recibe comentarios antes de publicar

Los API
· La API debe ser comprensible para el programador promedio

· Métodos sencillos para tareas sencillas

· Separe la funcionalidad de la salida

· Nombramiento consistente de subrutinas o métodos

· Utilice parámetros con nombre (un hash o hashref) cuando hay más de dos parámetros

Estabilidad
· Asegúrese de que su módulo funcione con "use estricto" y "-w"

· Los módulos estables deben mantener la compatibilidad con versiones anteriores

Documentación
· Escribir documentación en POD

· Documentar el propósito, el alcance y las aplicaciones de destino

· Documentar cada método o subrutina de acceso público, incluidos los parámetros y la devolución
valores

· Da ejemplos de uso en tu documentación.

· Proporcione un archivo README y quizás también notas de la versión, registro de cambios, etc.

· Proporcionar enlaces a más información (URL, correo electrónico)

tortugitas consideraciones
· Especifique los requisitos previos en Makefile.PL o Build.PL

· Especifique los requisitos de la versión de Perl con "usar"

· Incluya pruebas con su módulo

· Elija un esquema de numeración de versiones sensato y coherente (X.YY es el método común de Perl
esquema de numeración de módulos)

· Incrementar el número de versión para cada cambio, sin importar cuán pequeño sea

· Empaqueta el módulo usando "make dist"

· Elija una licencia adecuada (GPL / Artistic es un buen valor predeterminado)

ANTES Al EMPIEZA ESCRITURA A MÓDULO

Trate de no lanzarse precipitadamente al desarrollo de su módulo sin dedicar un tiempo a pensar
primero. Un poco de previsión puede ahorrarle una gran cantidad de esfuerzo más adelante.

Tiene it been done antes?
Es posible que ni siquiera necesite escribir el módulo. Compruebe si ya se ha hecho en Perl,
y evite reinventar la rueda a menos que tenga una buena razón.

Los buenos lugares para buscar módulos preexistentes incluyenhttp://search.cpan.org/> y
y preguntando "[email protected]"
(<http://lists.perl.org/list/module-authors.html>).

Si un módulo existente casi hace lo que quiere, considere escribir un parche, escribir un
subclase, o ampliando el módulo existente en lugar de reescribirlo.

Do one cosa y do it well
A riesgo de decir lo obvio, los módulos están pensados ​​para ser modulares. Un desarrollador de Perl
debe poder utilizar módulos para armar los componentes básicos de su aplicación.
Sin embargo, es importante que los bloques tengan la forma correcta y que el desarrollador
no debería tener que usar un bloque grande cuando todo lo que necesitan es uno pequeño.

Su módulo debe tener un alcance claramente definido que no sea más largo que una sola oración.
¿Se puede dividir su módulo en una familia de módulos relacionados?

Mal ejemplo:

"FooBar.pm proporciona una implementación del protocolo FOO y el estándar BAR relacionado".

Buen ejemplo:

"Foo.pm proporciona una implementación del protocolo FOO. Bar.pm implementa el BAR relacionado
protocolo."

Esto significa que si un desarrollador solo necesita un módulo para el estándar BAR, no debe
verse obligado a instalar bibliotecas para FOO también.

Qué está haciendo in a ¿nombre?
Asegúrese de elegir un nombre apropiado para su módulo desde el principio. Esto ayudará a la gente
encuentre y recuerde su módulo, y haga que la programación con su módulo sea más intuitiva.

Al nombrar su módulo, tenga en cuenta lo siguiente:

· Sea descriptivo (es decir, describa con precisión el propósito del módulo).

· Sea coherente con los módulos existentes.

· Refleja la funcionalidad del módulo, no la implementación.

· Evite iniciar una nueva jerarquía de nivel superior, especialmente si ya existe una jerarquía adecuada
existe bajo el cual podría colocar su módulo.

Get realimentación antes publicación
Si nunca ha subido un módulo a CPAN antes (e incluso si lo ha hecho), está
Se recomienda encarecidamente recibir comentarios sobre PrePAN.http://prepan.org>. PrePAN es un sitio
dedicado a discutir ideas para módulos CPAN con otros desarrolladores de Perl y es una gran
recurso para desarrolladores de Perl nuevos (y experimentados).

También debe intentar obtener comentarios de personas que ya estén familiarizadas con el módulo.
dominio de la aplicación y el sistema de nombres CPAN. Autores de módulos o módulos similares
con nombres similares, puede ser un buen lugar para comenzar, al igual que los sitios comunitarios como Perl Monks
<http://www.perlmonks.org>.

DISEÑO Y ESCRITURA TU MÓDULO

Consideraciones para el diseño y codificación de módulos:

A OO or no a ¿OOO?
Su módulo puede estar orientado a objetos (OO) o no, o puede tener ambos tipos de interfaces
disponible. Hay pros y contras de cada técnica, que deben tenerse en cuenta cuando
diseña tu API.

In Perl Mejores Clínicas de Prácticas (copyright 2004, publicado por O'Reilly Media, Inc.), Damian Conway
proporciona una lista de criterios para usar al decidir si OO es el adecuado para su problema:

· El sistema que se está diseñando es grande o es probable que lo sea.

· Los datos se pueden agregar en estructuras obvias, especialmente si hay una gran
cantidad de datos en cada agregado.

· Los diversos tipos de datos agregados forman una jerarquía natural que facilita el uso
de herencia y polimorfismo.

· Tiene un dato sobre el que se aplican muchas operaciones diferentes.

· Debe realizar las mismas operaciones generales en tipos de datos relacionados, pero con
ligeras variaciones dependiendo del tipo específico de datos que se apliquen las operaciones
a.

· Es probable que tenga que agregar nuevos tipos de datos más adelante.

· Las interacciones típicas entre piezas de datos están mejor representadas por operadores.

· Es probable que la implementación de componentes individuales del sistema cambie
en las transacciones.

· El diseño del sistema ya está orientado a objetos.

· Un gran número de otros programadores utilizarán sus módulos de código.

Piense detenidamente si OO es apropiado para su módulo. Objeto gratuito
La orientación da como resultado API complejas que son difíciles para el usuario promedio del módulo
entender o utilizar.

Diseño a tu manera API
Sus interfaces deben ser comprensibles para un programador de Perl promedio. La siguiente
Las pautas pueden ayudarlo a juzgar si su API es lo suficientemente sencilla:

Escribe rutinas sencillas para hacer cosas sencillas.
Es mejor tener numerosas rutinas simples que unas pocas monolíticas. Si tu
La rutina cambia su comportamiento significativamente en función de sus argumentos, es una señal de que
debe tener dos (o más) rutinas separadas.

Separe la funcionalidad de la salida.
Devuelva sus resultados en la forma más genérica posible y permita que el usuario elija cómo
para usarlos. La forma más genérica posible suele ser una estructura de datos Perl que
luego se puede usar para generar un informe de texto, HTML, XML, una consulta de base de datos o lo que sea
más sus usuarios requieren.

Si su rutina recorre algún tipo de lista (como una lista de archivos o
registros en una base de datos) puede considerar proporcionar una devolución de llamada para que los usuarios puedan
manipular cada elemento de la lista por turno. File :: Find proporciona un ejemplo de esto
con su sintaxis "buscar (\ & deseado, $ dir)".

Proporcione atajos y valores predeterminados razonables.
No requiera que todos los usuarios del módulo pasen por los mismos aros para lograr un simple
resultado. Siempre puede incluir parámetros opcionales o rutinas para más complejos o
comportamiento no estándar. Si la mayoría de sus usuarios tiene que escribir unos pocos casi idénticos
líneas de código cuando comienzan a usar su módulo, es una señal de que debería haber hecho
ese comportamiento es un defecto. Otro buen indicador de que debe utilizar valores predeterminados es si
la mayoría de sus usuarios llaman a sus rutinas con los mismos argumentos.

Convenciones de nombres
Tu nombre debe ser coherente. Por ejemplo, es mejor tener:

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

than

display_day ();
semana_display ();
show_year ();

Esto se aplica igualmente a los nombres de métodos, nombres de parámetros y cualquier otra cosa que sea
visible para el usuario (¡y la mayoría de las cosas que no lo son!)

Paso de parámetros
Utilice parámetros con nombre. Es más fácil usar un hash como este:

$ obj-> hacer_algo (
nombre => "wibble",
tipo => "texto",
tamaño => 1024,
);

... que tener una larga lista de parámetros sin nombre como este:

$ obj-> hacer_algo ("wibble", "texto", 1024);

Si bien la lista de argumentos puede funcionar bien para uno, dos o incluso tres argumentos, cualquier
más argumentos se vuelven difíciles de recordar para el usuario del módulo y difíciles para el módulo
autor para administrar. Si desea agregar un nuevo parámetro, tendrá que agregarlo al
final de la lista para compatibilidad con versiones anteriores, y esto probablemente hará que su lista
orden poco intuitivo. Además, si muchos elementos pueden no estar definidos, es posible que vea lo siguiente
llamadas a métodos poco atractivos:

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

Proporcione valores predeterminados sensibles para los parámetros que los tengan. No hagas que tus usuarios
especificar parámetros que casi siempre serán los mismos.

La cuestión de si pasar los argumentos en un hash o en un hashref es en gran medida un asunto
de estilo personal.

El uso de claves hash que comienzan con un guión ("-nombre") o completamente en mayúsculas
("NAME") es una reliquia de versiones anteriores de Perl en las que las cadenas en minúsculas ordinarias
no fueron manejados correctamente por el operador "=>". Mientras que algunos módulos conservan mayúsculas
o claves de argumentos con guiones por razones históricas o como una cuestión de estilo personal,
la mayoría de los módulos nuevos deberían utilizar teclas simples en minúsculas. Lo que elijas, sé
¡consistente!

Rigor y advertencias
Su módulo debe ejecutarse con éxito bajo el estricto pragma y debe ejecutarse sin
generando advertencias. Su módulo también debe manejar la verificación de corrupción cuando corresponda,
aunque esto puede causar dificultades en muchos casos.

Hacia atrás compatibilidad
Los módulos que son "estables" no deben romper la compatibilidad con versiones anteriores sin al menos un
larga fase de transición y un cambio importante en el número de versión.

Error manipulación y la vida
Cuando su módulo encuentra un error, debe hacer una o más de las siguientes:

· Devuelve un valor indefinido.

· Set $ ​​Module :: errstr o similar ("errstr" es un nombre común usado por DBI y otros
módulos populares; si elige otra cosa, asegúrese de documentarlo claramente).

· "Advertir ()" o "carpa ()" un mensaje a STDERR.

· "Croak ()" sólo cuando su módulo no puede averiguar qué hacer. ("croar()"
es una mejor versión de "die ()" para su uso dentro de los módulos, que informa sus errores desde
la perspectiva de la persona que llama. Consulte Carpa para obtener detalles sobre "croak ()", "carp ()" y otros
rutinas útiles.)

· Como alternativa a lo anterior, es posible que prefiera lanzar excepciones utilizando el Error
módulo.

El manejo de errores configurable puede ser muy útil para sus usuarios. Considere ofrecer una opción
de niveles para mensajes de advertencia y depuración, una opción para enviar mensajes a un archivo separado, un
forma de especificar una rutina de manejo de errores, u otras características similares. Asegúrese de predeterminar todos
estas opciones para el uso más común.

DOCUMENTAR TU MÓDULO

POD
Su módulo debe incluir documentación dirigida a desarrolladores de Perl. Deberías usar Perl's
"documentación antigua simple" (POD) para su documentación técnica general, aunque puede
desea escribir documentación adicional (documentos técnicos, tutoriales, etc.) en algún otro
formato. Debes cubrir los siguientes temas:

· Una sinopsis de los usos comunes del módulo

· El propósito, el alcance y las aplicaciones de destino de su módulo

· Uso de cada método o subrutina de acceso público, incluidos los parámetros y
valores devueltos

· Ejemplos de uso

· Fuentes de información adicional

· Una dirección de correo electrónico de contacto para el autor / mantenedor

El nivel de detalle en la documentación del módulo Perl generalmente va de menos detallado a más
detallado. Su sección SINOPSIS debe contener un ejemplo mínimo de uso (tal vez como
poco como una línea de código; omita los casos de uso inusuales o cualquier cosa que no necesite la mayoría
usuarios); La DESCRIPCIÓN debe describir su módulo en términos amplios, generalmente en solo una
pocos párrafos; más detalles de las rutinas o métodos del módulo, ejemplos de código extensos o
En las secciones siguientes se debe proporcionar otro material en profundidad.

Idealmente, alguien que esté un poco familiarizado con su módulo debería poder actualizar su
memoria sin presionar "página abajo". A medida que su lector continúa a través del documento,
debería recibir una cantidad progresivamente mayor de conocimientos.

El orden recomendado de las secciones en la documentación del módulo Perl es:

· NOMBRE

· SINOPSIS

· DESCRIPCION

· Una o más secciones o subsecciones que brindan mayor detalle de los métodos disponibles y
rutinas y cualquier otra información relevante.

· ERRORES / AVISOS / etc

· AUTOR

· VER TAMBIÉN

· DERECHOS DE AUTOR y LICENCIA

Mantenga su documentación cerca del código que documenta (documentación "en línea"). Incluir POD
para un método dado justo encima de la subrutina de ese método. Esto hace que sea más fácil mantener el
documentación actualizada, y evita tener que documentar cada fragmento de código dos veces (una vez en
POD y una vez en los comentarios).

LÉAME, INSTALAR EN PC, , notas, registros de cambios
Su módulo también debe incluir un archivo README que describa el módulo y proporcione indicaciones para
más información (sitio web, correo electrónico del autor).

Se debe incluir un archivo INSTALL, que debe contener instrucciones de instalación simples.
Cuando use ExtUtils :: MakeMaker, esto generalmente será:

Perl Makefile.PL
“piensen de nuevo sobre los incrementos de precio”
hacer prueba
make install

Cuando use Module :: Build, esto generalmente será:

Perl Build.PL
compilación perl
prueba de compilación de perl
instalación de compilación de perl

Deben producirse notas de la versión o registros de cambios para cada versión de su software
describir los cambios visibles para el usuario en su módulo, en términos relevantes para el usuario.

A menos que tenga buenas razones para usar algún otro formato (por ejemplo, un formato usado
dentro de su empresa), la convención es nombrar su archivo de registro de cambios "Cambios" y
siga el formato simple descrito en CPAN :: Cambios :: Espec.

LIBERAR CONSIDERACIONES

Versión numeración
Los números de versión deben indicar al menos versiones mayores y menores, y posiblemente sub-menores
lanzamientos. Una versión importante es aquella en la que la mayor parte de la funcionalidad ha cambiado, o en
qué nueva funcionalidad importante se agrega. Una versión menor es aquella en la que una pequeña cantidad de
se ha agregado o cambiado la funcionalidad. Los números de versión secundaria se utilizan normalmente para
cambios que no afectan la funcionalidad, como parches de documentación.

El esquema de numeración de versiones de CPAN más común se ve así:

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

Un número de versión de CPAN correcto es un número de punto flotante con al menos 2 dígitos después del
decimal. Puede probar si se ajusta a CPAN utilizando

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

Si desea lanzar una versión 'beta' o 'alfa' de un módulo pero no quiere que CPAN.pm
anótelo como el más reciente, use un '_' después del número de versión normal seguido de al menos 2
dígitos, p. ej. 1.20_01. Si hace esto, se recomienda el siguiente idioma:

nuestra $ VERSION = "1.12_01"; # para que la distribución de CPAN tenga
# nombre de archivo correcto
nuestro $ XS_VERSION = $ VERSION; # solo es necesario si tiene código XS
$ VERSION = eval $ VERSION; # por lo que "use Module 0.002" no advertirá en
# guion bajo

Con ese truco, MakeMaker solo leerá la primera línea y, por lo tanto, leerá el guión bajo,
mientras que el intérprete de perl evaluará $ VERSION y convertirá la cadena en una
número. Las operaciones posteriores que tratan $ VERSION como un número podrán hacerlo
sin provocar una advertencia acerca de que $ VERSION no es un número.

Nunca publique nada (incluso un parche de documentación de una palabra) sin incrementar el
número. Incluso un parche de documentación de una palabra debería resultar en un cambio en la versión en el
nivel sub-menor.

Una vez elegido, es importante ceñirse a su esquema de versión, sin reducir el número
de dígitos. Esto se debe a que los empaquetadores "descendentes", como el sistema de puertos FreeBSD,
interpretar los números de versión de varias formas. Si cambia el número de dígitos en su
esquema de versión, puede confundir estos sistemas para que obtengan las versiones de su módulo
de orden, lo que obviamente es malo.

Pre-requisitos
Los autores de módulos deben considerar cuidadosamente si se basan en otros módulos y cuáles
módulos en los que confiar.

Lo más importante es elegir módulos que sean lo más estables posible. En orden de preferencia:

· Módulos básicos de Perl

· Módulos CPAN estables

· Módulos CPAN inestables

· Módulos no disponibles de CPAN

Especifique los requisitos de versión para otros módulos de Perl en los requisitos previos en su
Makefile.PL o Build.PL.

Asegúrese de especificar los requisitos de la versión de Perl tanto en Makefile.PL o Build.PL como con
"requiere 5.6.1" o similar. Consulte la sección "use VERSION" de "require" en perlfunc para
Detalles.

Pruebas
Todos los módulos deben probarse antes de la distribución (utilizando "make disttest"), y las pruebas
también debería estar disponible para las personas que instalan los módulos (usando "make test"). Para
Module :: Build usted usaría el "make test" equivalente a "perl Build test".

La importancia de estas pruebas es proporcional a la supuesta estabilidad de un módulo. A
módulo que pretende ser estable o que espera lograr un uso amplio debe cumplir como
estricto un régimen de pruebas como sea posible.

Módulos útiles para ayudarlo a escribir pruebas (con un impacto mínimo en su proceso de desarrollo o
su tiempo) incluyen Test :: Simple, Carp :: Assert y Test :: Inline. Para mas sofisticado
suites de prueba hay Test :: More y Test :: MockObject.

Embalaje
Los módulos deben empaquetarse utilizando una de las herramientas de empaquetado estándar. Actualmente tienes
la elección entre ExtUtils :: MakeMaker y el módulo más independiente de la plataforma :: Build,
permitiendo que los módulos se instalen de manera consistente. Al usar ExtUtils :: MakeMaker,
puede utilizar "make dist" para crear su paquete. Existen herramientas para ayudarlo a construir su
módulo en un estilo compatible con MakeMaker. Estos incluyen ExtUtils :: ModuleMaker y h2xs. Ver
también perlnewmod.

Licencias
Asegúrese de que su módulo tenga una licencia y de que el texto completo esté incluido en el
distribución (a menos que sea común y los términos de la licencia no requieran que
incluirlo).

Si no sabe qué licencia usar, doble licencia bajo la GPL y licencias artísticas
(lo mismo que el propio Perl) es una buena idea. Ver perlgpl y perlartistic.

COMÚN ERRORES

Reinventar los rueda
Hay ciertos espacios de aplicación que ya están muy, muy bien atendidos por CPAN.
Un ejemplo son los sistemas de plantillas, otro son los módulos de fecha y hora, y hay muchos
más. Si bien es un rito de iniciación escribir su propia versión de estas cosas, por favor
considere cuidadosamente si el mundo de Perl realmente necesita que lo publique.

Molesto a do demasiado mucho más
Su módulo será parte de un conjunto de herramientas para desarrolladores. No formará, en sí mismo, el
toda kit de herramientas. Es tentador agregar funciones adicionales hasta que su código sea monolítico
sistema en lugar de un conjunto de bloques de construcción modulares.

Inapropiado documentación
No caiga en la trampa de escribir para la audiencia equivocada. Tu audiencia principal es una
Desarrollador con experiencia razonable con al menos un conocimiento moderado de las características de su módulo.
dominio de la aplicación, que acaba de descargar su módulo y quiere empezar a usarlo como
lo mas rapido posible.

Los tutoriales, la documentación del usuario final, los artículos de investigación, las preguntas frecuentes, etc.no son apropiados en un
la documentación principal del módulo. Si realmente desea escribirlos, inclúyalos como sub-
documentos como "Mi :: Módulo :: Tutorial" o "Mi :: Módulo :: Preguntas frecuentes" y proporcionar un enlace en el
VEA TAMBIÉN la sección de la documentación principal.

Utilice perlmodstyle en línea utilizando los servicios de onworks.net