perlmodstyle.pod

NOMBRE

perlmodstyle - Guía de estilo de los módulos Perl

INTRODUCCIÓN

Este documento intenta describir las "mejores prácticas" de la Comunidad Perl para la escritura de módulos Perl. Extiende las recomendaciones que se encuentran en perlstyle, que debe ser considerado de lectura obligatoria antes de leer este documento.

Aunque este documento está destinado a ser útil a todos los autores de módulos, está especialmente dirigido a autores que desean 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 sólo son vistos por los desarrolladores del módulo. Sin embargo, muchas de las directrices que se presentan en este documento puede ser extrapoladas y aplicadas con éxito a un módulo de uso particular.

Este documento se diferencia de perlnewmod en que se trata de una guía de estilo en lugar de un manual sobre la creación de módulos de CPAN. Proporciona una lista de control contra el que los módulos se pueden comparar para determinar si se ajustan a las mejores prácticas, sin que necesariamente se describe en detalle cómo lograrlo.

Todos los consejos que figuran en este documento ha sido obtenidos de largas conversaciones con autores experimentados CPAN y los usuarios. Cada consejo que aquí se da es el resultado de errores anteriores. Esta información está aquí para ayudarle a evitar los mismos errores y el trabajo extra que, inevitablemente, tendría que invertir en arreglarlos.

La primera sección de este documento ofrece una lista detallada; las secciones siguientes proporcionan una descripción más detallada de los elementos de la lista. La sección final, "Errores comunes", describe algunos de los errores más populares hechas por los autores de CPAN.

RESUMEN LISTA DE CONTROL

Para más detalles sobre cada elemento de esta lista, vea más adelante.

Antes de empezar

• No vuelva a reinventar la rueda

• Parchee, amplíe o derive de un módulo existente siempre que sea posible

• Haga una cosa y hágala bien

• Elija un nombre apropiado

• Obtenga comentarios positivos antes de publicarlo

LA API

• La API debe ser comprensible para un programador medio

• Métodos sencillos para tareas sencillas

• Separe la funcionalidad de la salida

• Denominación consistente de subrutinas o métodos

• Use parámetros nominados (un hash o referencia a un hash) cuando haya más de dos parámetros

Estabilidad

• Asegúrese de que su módulo funciona bajo use strict y -w

• Módulos estables deben mantener la compatibilidad hacia atrás

Documentación

• Escriba documentación en POD

• Documente el propósito, ámbito y las aplicaciones objetivo

• Documente cada método públicamente accesible o subrutina, incluyendo parámetros y valores de retorno

• Dé ejemplos de uso en la documentación

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

• Ofrezca enlaces a información adicional (URL, correo electrónico)

Consideraciones del lanzamiento

• Especifique los prerequisitos previos en Makefile.PL o Build.PL

• Especifique los requisitos de la versión de Perl con use

• Incluya test con su módulo

• Elija una sensata y coherente esquema de numeración de versiones (X.YY es el esquema de numeración normal para los módulos Perl)

• Incremente el número de versión para cada cambio, por pequeño que sea

• Empaquete el módulo con "make dist"

• Elija una licencia adecuada (GPL/Artística es un buen valor por defecto)

ANTES DE COMENZAR A ESCRIBIR UN MÓDULO

Trate de no poner en marcha, de memoria, el desarrollo de su módulo, sin pasar en primer lugar algún tiempo pensándolo. Un poco de previsión puede ahorrar una gran cantidad de esfuerzo más adelante.

¿Se ha hecho antes?

Puede que ni siquiera tenga que escribir el módulo. Compruebe si ya se ha hecho en Perl, y evitará tener que volver a inventar la rueda, a menos que tenga una buena razón.

Buenos lugares para mirar por módulos existentes, incluye a http://search.cpan.org/ y https://metacpan.org, y preguntando en module-authors@perl.org (http://lists.perl.org/list/module-authors.html).

Si un ya existente módulo casi hace lo que quiere, considere escribir un parche, escribir una subclase o, de otra manera, extienda el módulo actual en lugar de reescribirlo.

Haga una cosa y hágala bien

A riesgo de afirmar lo obvio, los módulos están destinados a ser modulares. Un programador de Perl debe ser capaz de utilizar módulos para armar los bloques de construcción de su aplicación. Sin embargo, es importante que los bloques estén en la forma correcta, y que el desarrollador no debería tener que utilizar un bloque grande cuando todo lo que necesita es uno pequeño.

Su módulo debe tener un ámbito claramente definido que no es más que una sola instrucción. ¿Puede su módulo dividirse en una familia de módulos relacionados?

Mal ejemplo:

"FooBar.pm proporciona una implementación del protocolo FOO y la norma BAR relacionada".

Buen ejemplo:

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

Esto significa que si un desarrollador sólo necesita un módulo para el estándar BAR, no debe verse obligado a instalar las bibliotecas para FOO.

¿Qué hay en un nombre?

Asegúrese de elegir un nombre apropiado para el módulo desde el principio. Esto ayudará a la gente a encontrar y recordar su módulo, y hacer la programación con el módulo de forma más intuitiva.

Al escribir el nombre del módulo, considere lo siguiente:

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

• Sea consistente con los módulos existentes.

• Refleje la funcionalidad del módulo, no la implementación.

• Evite comenzar una nueva jerarquía de nivel superior, sobre todo si una jerarquía adecuada ya existe en virtud del cual se puede colocar su módulo.

Obtenga comentarios positivos antes de publicarlo

Si nunca ha subido un módulo a CPAN (e incluso si lo ha hecho), se le anima a que obtenga comentarios positivos en PrePAN. PrePAN es un sitio dedicado a hablar de ideas sobre módulos CPAN con otros desarrolladores Perl y es una gran fuente de recursos para las nuevos (y experimentados) desarrolladores Perl.

También debería tratar de conseguir comentarios positivos de las personas que ya están familiarizadas con el dominio de aplicación del módulo y el sistema de nombres de CPAN. Los autores de módulos similares, o módulos con nombres similares, pueden ser un buen lugar para comenzar, así como en sitios de la comunidad como Perl Monks

DISEÑANDO Y ESCRIBIENDO SU MÓDULO

Consideraciones para el diseño y codificación del módulo:

¿POO o no POO?

Su módulo puede estar orientado a objetos (POO) o no, o puede tener ambos tipos de interfaces disponibles. Hay pros y contras de cada técnica, lo que debería tenerse en cuenta al diseñar su API.

En Perl Best Practices (copyright 2004, publicado por O'Reilly Media, Inc.), Damian Conway ofrece una lista de criterios a utilizar cuando hay que decidir si OO es el sistema más adecuado para su problema:

• El sistema que se está diseñando es grande o puede llegar a serlo.

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

• Los distintos tipos de datos agregados forman una jerarquía natural que facilita el uso de la herencia y el polimorfismo.

• Tiene datos a los que hay que aplicar muchas operaciones diferentes.

• Es necesario llevar a cabo las mismas operaciones generales sobre tipos de datos relacionados, pero con ligeras variaciones en función del tipo de datos específico al que se aplican estas operaciones.

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

• Las interacciones típicas entre elementos de datos se representan mejor mediante operadores.

• Es probable que la implementación de componentes individuales del sistema cambie con el tiempo.

• El diseño del sistema ya es orientado a objetos.

• Muchos programadores van a utilizar sus módulos de código.

Piense con cuidado acerca de si la POO es apropiada para su módulo. Una orientación a objetos injustificada resulta en unas API complejas que serán difíciles de comprender o utilizar para el usuario medio del módulo.

El diseño de su API

Su interfaz debe ser comprensible para un programador promedio de Perl. Las siguientes pautas pueden ayudar a juzgar si su API es suficientemente clara:

Escriba rutinas sencillas para hacer cosas simples.

Es mejor tener muchas rutinas sencillas que unas pocas monolíticas. Si su rutina cambia su comportamiento de manera significativa sobre la base de sus argumentos, es una señal de que debe tener dos (o más) rutinas separadas.

Separe la funcionalidad de la salida.

Muestre los resultados en su forma más genérica posible y permita al usuario elegir la forma de utilizarlos. La forma más genérica posible, es por lo general una estructura de datos Perl, que puede ser utilizado para generar un informe de texto, HTML, XML, una consulta de base de datos o cualquier otra cosa que necesiten los usuarios.

Si la rutina se repite a través de algún tipo de lista (por ejemplo, una lista de archivos o registros en una base de datos), puede considerar la posibilidad de una retrollamada (callback) para que los usuarios puedan manipular cada elemento de la lista cada vez. File::Find ofrece un ejemplo de esto con su sintaxis find(\&buscado, $dir).

Proporcione atajos y valores por defecto razonables.

No exija a cada usuario del módulo saltar a través de los mismos aros para lograr un resultado sencillo. Siempre puede incluir parámetros opcionales o rutinas para un comportamiento más complejo o no estándar. Si la mayoría de los usuarios tienen que escribir unas pocas líneas casi idénticas de código cuando empiezan a usar su módulo, es una señal de que debería haber hecho este comportamiento por defecto. Otro buen indicador de que debe usar valores por defecto es si la mayor parte de los usuarios llama a sus rutinas con los mismos argumentos.

Convenciones de nombres

Su nombramiento debe ser coherente. Por ejemplo, es mejor tener:

muestra_día();
muestra_semana();
muestra_año();

que

muestra_día();
semana_muestra();
show_year();

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

Paso de parámetros

Use parámetros con nombre. Es más fácil utilizar un hash de esta manera:

$obj->hacer_algo(
            nombre => "wibble",
            tipo => "texto",
            size => 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, los siguientes argumentos le serán más difícil de recordar para el usuario del módulo, y difícil de mantener para el autor del módulo. Si desea agregar un nuevo parámetro lo tendrá que añadir al final de la lista, para mantener la compatibilidad con versiones anteriores, y esto probablemente hará que su orden de lista sea poco intuitivo. Además, si muchos elementos pueden estar indefinidos puede ver las siguientes poco atractivas llamadas de métodos:

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

Proporcione parámetros por defecto para los parámetros que los tengan. No haga que los usuarios especifiquen parámetros que casi siempre sean los mismos.

La cuestión de si se debe pasar los argumentos en un hash o una referencia a un hash es en gran medida una cuestión de estilo personal.

El uso de claves hash comenzando con un guión (-name) o totalmente en mayúsculas (NOMBRE) es una reliquia de las versiones anteriores de Perl en el que las cadenas en minúscula no se gestionaban correctamente por el operador =>. Si bien algunos módulos retienen los argumentos en mayúsculas o con guión por razones históricas o como una cuestión de estilo personal, la mayoría de los nuevos módulos deberían utilizar las claves escritas en minúsculas. Lo que elija, ¡debe ser coherente!

Rigor y advertencias

Su módulo debe funcionar con éxito bajo el pragma strict y debe funcionar sin generar ninguna advertencia. El módulo también debe gestionar comprobaciones de pringue, aunque esto puede causar dificultades en muchos casos.

Compatibilidad con versiones anteriores

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

Control de errores y mensajes

Cuando el módulo se encuentre con un error debe hacer uno o más de:

• Devolver un valor indefinido.

• poner $Module::errstr o similar (errstr es un nombre común usado por DBI y otros módulos populares; si elije otro, asegúrese de documentarlo claramente).

• Un mensaje warn() o carp() a STDERR.

• croak() solo cuando el módulo no puede averiguar, de forma absoluta, qué debe de hacer. (croak() es una versión mejorada de die() para usar dentro de los módulos, que reporta sus errores desde la perspectiva del llamador. Vea Carp para más detalles sobre croak(), carp() y otras rutinas útiles).

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

Una gestión configurable de errores puede ser muy útil para los usuarios. Considere la posibilidad de ofrecer una selección de niveles de alerta y mensajes de depuración, una opción para enviar mensajes a un archivo separado, una forma de especificar una rutina de control de errores, o de otras características. Asegúrese de que todas estas opciones estén puestas, por defecto, para el uso más común.

DOCUMENTANDO SU MÓDULO

POD

Su módulo debe incluir la documentación dirigida a los desarrolladores de Perl. Debe usar "documentación simple y llana" de Perl (POD) para su documentación técnica en general, aunque es posible que desee escribir documentación adicional (papeles, manuales, etc) en algún otro formato. Es necesario que cubra los siguientes temas:

• Una sinopsis de los usos comunes del módulo

• El propósito, ámbito y las aplicaciones objetivo de su módulo

• El uso de cada método o subrutina públicamente accesible, incluidos los parámetros y valores devueltos

• Ejemplos de uso

• Fuentes de información adicional

• Una dirección de correo electrónico de contacto del autor/mantenedor

El nivel de detalle en la documentación general del módulo Perl, va de menos a más detallada. Su sección SINOPSIS debe contener un ejemplo mínimo de uso (quizás tan sólo una línea de código; evitar los casos de uso inusuales o cualquier cosa que no sea necesaria para la mayoría de los usuarios); la DESCRIPCIÓN debe describir el módulo en términos generales, por lo general en sólo unos pocos párrafos; más detalles de las rutinas del módulo o métodos, ejemplos con código más largo, u otro material en profundidad se debe dar en las secciones siguientes.

Lo ideal sería que alguien que está un poco familiarizado con el módulo debería ser capaz de refrescar su memoria sin tener que pulsar el "avance de página". A medida que el lector siga a través del documento, debe recibir una cantidad cada vez mayor de conocimientos.

El orden recomendado de las secciones de documentación de un módulo Perl es:

• NOMBRE

• SINOPSIS

• DESCRIPCIÓN

• Una o más secciones o subsecciones dando mayor detalle de los métodos disponibles y las rutinas y cualquier otra información pertinente.

• ERRORES/ADVERTENCIAS/etc

• AUTOR

• VEA TAMBIÉN

• COPYRIGHT y LICENCIA

Mantenga la documentación cerca del código que documenta (documentación "en línea"). Incluya POD para un determinado método justo por encima de la subrutina del método. Esto hace que sea más fácil mantener la documentación al día, y evita tener que documentar cada pieza de código dos veces (una en POD y otra vez en los comentarios).

README, INSTALL, notas de lanzamiento, changelogs

El módulo también debe incluir un archivo README que describa el módulo y dé consejos para obtener más información (página web, correo electrónico del autor).

Un archivo INSTALL debe ser incluido, y debe contener las más sencillas instrucciones de instalación. Cuando se utiliza ExtUtils::MakeMaker serán algo así:

perl Makefile.PL

make

make test

make install

Al utilizar el Module::Build, suele ser así:

perl Build.PL

perl Build

perl Build test

perl Build install

Notas de versión o las listas de cambios deben producirse para cada versión de su software que describa los cambios visibles de su módulo, en términos relevantes para el usuario.

A menos que tenga una buena razón para utilizar algún otro formato (por ejemplo, un formato utilizado en su empresa), la convención es nombrar el archivo de cambios como Changes, y seguir el formato sencillo descrito en CPAN::Changes::Spec.

CONSIDERACIONES DEL LANZAMIENTO

Numerado de versión

Los números de versión deben indicar al menos las versiones principales y secundarias, y posiblemente, versiones menores. Una versión principal es aquella en la que la mayor parte de la funcionalidad ha cambiado, o en los que se ha añadido una nueva funcionalidad importante. Una versión menor es aquella en la que una pequeña cantidad de funcionalidad ha sido añadida o cambiada. Números de versión de menor importancia se utilizan generalmente para los cambios que no afectan a la funcionalidad, tales como los parches en la documentación.

El esquema de numeración de versiones más común en CPAN es el siguiente:

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

Un número correcto de versión en CPAN es un número de punto flotante con al menos dos dígitos después del decimal. Se puede comprobar si se ajusta a CPAN utilizando

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

Si desea liberar una versión 'beta' o 'alfa' de un módulo, pero no quiere que CPAN.pm lo liste, use un '_' después del número de versión normal seguido por al menos dos dígitos, por ejemplo. 1.20_01. Si hace esto, se recomienda usar el siguiente modismo:

our $VERSION = "1.12_01"; # así la distribución CPAN tendrá
                          # el nombre de archivo correcto
our $XS_VERSION = $VERSION; # solo necesario si tiene código XS
$VERSION = eval $VERSION; # así, "use Module 0.002" no saltará
                          # bajo guión

Con este truco MakeMaker sólo leerá la primera línea y, por tanto, leerá el guión bajo, mientras que el intérprete de perl evaluará la $VERSION y convertirá la cadena en un número. Operaciones ulteriores que traten con $VERSION como un número, podrán hacerlo sin provocar una advertencia sobre si $VERSION no es un número.

Nunca lance nada (ni siquiera un parche de documentación de una sola palabra) sin incrementar el número. Incluso un parche de la documentación de una sola palabra debe dar lugar a un cambio en la versión de nivel más bajo.

Una vez elegido, es importante aferrarse a su esquema de versionado, sin reducir el número de dígitos. Esto es porque empaquetadores "de terceros", como las distintas versiones del sistema FreeBSD, interpretan los números de versión de formas diferentes. Si cambia el número de dígitos en su esquema de versionado, puede confundir a estos sistemas, así que ellos obtendrán las versiones de su módulo fuera de orden, que es algo, obviamente, malo.

Pre-requisitos

Los autores de módulos deben considerar cuidadosamente si se basan en otros módulos, y en qué módulos quieren confiar.

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

• Módulos pertenecientes al núcleo de Perl

• Módulos estables de CPAN

• Módulos inestables de CPAN

• Módulos no disponibles en CPAN

Especifique los requisitos de versión para otros módulos Perl en los pre-requisitos de 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 y con require 5.6.1 o similar. Vea la sección use VERSION de "require" in perlfunc para más detalles.

Pruebas

Todos los módulos deben ser probados antes de su distribución (con "make disttest"), y las pruebas también deben estar disponibles para la gente que instala los módulos (con "make test"). Para Module::Build debe utilizar el equivalente de make test: perl Build test.

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

Módulos útiles que le ayudarán a escribir las pruebas (con un impacto mínimo en el proceso de desarrollo o de su tiempo) son Test::Simple, Carp::Assert y Test::Inline. Para obtener más bancos de pruebas sofisticadas use Test::More y Test::MockObject.

Empaquetado

Los módulos deben estar empaquetados con una de las herramientas de empaquetado estándar. Actualmente tiene la posibilidad de elegir entre ExtUtils::MakeMaker y la más independiente de la plataforma, Module::Build, permitiendo módulos que se instalen de una forma coherente. Cuando se utiliza ExtUtils::MakeMaker, puede usar "make dist" para crear el paquete. Existen herramientas para ayudarle a generar su módulo en un estilo amigable, como MakeMaker. Estos incluyen ExtUtils::ModuleMaker y h2xs. Vea también perlnewmod.

Licencias

Asegúrese de que el módulo tiene una licencia, y que el texto completo de la misma está incluida en la distribución (a menos que sea muy común y los términos de la licencia no requieran que la incluya).

Si no sabe qué licencia usar, es una buena idea el licenciamiento dual bajo la GPL y la licencia Artistic (la misma que Perl). Vea perlgpl y perlartistic.

ERRORES COMUNES

Reinventando la rueda

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

Tratar de hacer demasiado

Su módulo será parte del conjunto de herramientas del desarrollador. No formará, en sí mismo, el kit de herramientas entero. Es tentador añadir características adicionales hasta que su código sea un sistema monolítico en lugar de un conjunto de bloques de construcción modulares.

Documentación inapropiada

No caiga en la trampa de escribir para el público equivocado. Su público principal es un desarrollador bastante experimentado con al menos un conocimiento moderado del dominio de aplicación de su módulo, que acaba de descargar su módulo y quiere empezar a utilizarlo tan pronto como sea posible.

Manuales, documentación de usuario final, documentos de investigación, P+F (FAQ), etc, no son apropiadas en la documentación principal de un módulo. Si realmente quieres escribirlos, inclúyalos como sub-documentos, tales como My::Module::Tutorial o My::Module::FAQ y proporcione un enlace en la sección VEA TAMBIÉN de la documentación principal.

VEA TAMBIÉN

perlstyle

Guía de estilo general programación Perl

perlnewmod

Cómo crear un nuevo módulo

perlpod

Documentación POD

podchecker

Comprueba la exactitud de tu POD

Herramientas de empaquetado

ExtUtils::MakeMaker, Module::Build

Herramientas de prueba

Test::Simple, Test::Inline, Carp::Assert, Test::More, Test::MockObject

http://pause.perl.org/

Servidor de subidas para los autores Perl (Perl Authors Upload Server). Contiene enlaces de información para los autores de módulos.

Cualquier buen libro de ingeniería del software

AUTOR

Kirrily "Skud" Robert <skud@cpan.org>

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 3:

Non-ASCII character seen before =encoding in 'Guía'. Assuming UTF-8