Mejores prácticas para escribir código abierto Java

Question

¿Dónde puedo encontrar algunas prácticas recomendadas para escribir código Java de código abierto? No busco instrucciones sobre cómo escribir el código propiamente dicho, sino sobre la distribución, el empaquetado, la documentación y todos los demás aspectos además de los archivos .java.

Mi objetivo es tomar un módulo que he escrito y publicarlo como de código abierto.

Editar - Todavía faltan instrucciones directas y concretas sobre lo que debe contener el archivo comprimido. ¿Hay convenciones para esto, o debería elegir una estructura razonable?

Answer 1

Ver el libro de Karl Fogel http://producingoss.com/ - fuente disponible en línea.

Answer 2

no estoy seguro de si va a haber un acuerdo universal sobre "mejores prácticas", pero los artículos que mencionas podría tener respuestas fáciles:

1. distribución es fácil con java.net o Sourceforge. Publicará su código usando sus estándares,
2. El empaquetado será de archivos ZIP. Es una buena idea crear un hash MD5 para que los clientes puedan verificar la integridad de sus descargas.
3. Documentación - sí, mucho por favor. Tenga javadocs separados y una guía de referencia que muestre cómo usar sus cosas.
4. Tiene un SVN público que permite acceso anónimo para que la gente pueda obtener y crear el último código por su cuenta.
5. Tener un gestor de fallos que permite a las personas para informar sobre errores, nuevas características, etc.
6. Establecer un wiki para la discusión, retroalimentación, etc.
7. Maven se ha convertido en un estándar de código abierto. Ten un buen pom.xml para aquellos aventureros que quieran echar un vistazo y construir tu código.
8. Las pruebas unitarias y la buena cobertura del código le ayudarán a demostrar su compromiso con la calidad.

Voy a tratar de pensar en más.

Answer 3

Creo que todo se reduce a la automatización del ciclo build-test-package-deploy. Idealmente, debería poder hacerlo con un solo clic (o con un solo comando de solicitud).

Personalmente, yo uso hormiga y definir un objetivo de desplegar el que hace lo siguiente

2. Construye todos los artefactos
3. Paquetes de los artefactos en una sola entrega (archivo .zip)
4. descomprime el zip en un directorio local
5. ejecuta los test de ese directorio local
6. Subida el .zip en SourceForge

Habiendo hecho eso, el único paso manual es definir un nuevo lanzamiento a través del sitio web de sourceforge.

Obviamente, para que este procedimiento sea efectivo, debe estar infectado con la prueba: escribo pruebas para cada nueva función que estoy implementando.

Answer 4

Si está buscando estructuras de directorios específicas, ¿por qué no mira los proyectos de código abierto existentes? Comenzaría con Jakarta Commons, que es un paquete muy usado.

Sin ninguna estadística que me respalde, diría que muchos proyectos usan una estructura de directorios similar a la especificada por Maven, incluso si no usan Maven en sí (y si puede pasar la curva de aprendizaje de Maven , es una buena herramienta de compilación el 90% del tiempo).

Answer 5

No estoy añadiendo que mucho, pero yo sugeriría lo siguiente:

Estructura de directorios

• tratar de hacer el javadocs completa, módulos de fuente más abiertas o bibliotecas no tienen muchas comentarios javadoc. Genere la documentación javadocs y colóquela en un directorio como apidocs. Si corresponde en los javadocs, debe especificar quién permite llamar a una clase y en qué circunstancias debe llamarse a la clase/función. Los ejemplos de código pequeño tampoco duelen y vale la pena agregarlos.
• Agregue un directorio "ejemplos" para ayudar los desarrolladores/usuarios utilizan/integran su módulo.
• Agregue los archivos de licencia en la raíz de su estructura de directorios y asegúrese de que cada uno de sus archivos tenga una licencia encabezado.
• añadir un archivo README en el directorio raíz de la distribución para información general y/o características específicas (enlace al software, autor, ayuda y apoyo, instalación instrucciones, etc.)
• Por lo general, la fuente el código va a un directorio src y la documentación va a la carpeta docs.

Embalaje

• Trate de distribuir su software en formatos apropiados (zip, tar.gz, DMG, exe, jar, etc.). Por ejemplo, para una aplicación web, tendría un zip, tar.gz, una guerra y tal vez un oído. Dependiendo del sitio web en el que se cargará, es posible que deba utilizar un formato de archivo como, por ejemplo, zip.
• crear un instalador si se aplica o no demasiado tedioso

Publishing

• Siga las instrucciones si procede a subir su módulo.

• publicidad de su módulo (blog, foros, Twitter, etc.)

  Siempre realizar pruebas adicionales cuando los envases o subir, algo inesperado podría ocurrir (archivo que falta, la corrupción de archivos, etc.).

Answer 6

Si su proyecto se llama Foo, a continuación, la versión XY deben empaquetarse en Foo-XYzip y descomprimir a Foo-XY/.... (en otras palabras, la trayectoria de cada archivo en el archivo debe comenzar con Foo-XY /)

Tenga un Foo-X.Y/README.txt que contenga instrucciones básicas como un archivo de texto sin formato. Al menos debería contener información sobre dónde está la documentación completa ("consulte docs/index.html para documentación") así como instrucciones breves sobre el uso ("agregar lib/Foo-XYjar a su ruta de clases") y reconstruir instrucciones (" ejecuta "ant build" para regenerar bibliotecas en lib y javadoc en apidoc/").

Si su proyecto necesita bibliotecas adicionales para trabajar o compilar, entonces automatice eso. Es decir. o deja que esto sea un proyecto de Maven o asegúrate de que funcione con Ant Ivy.

Sugeriría tener el código fuente en src /, las bibliotecas compiladas en lib /, la documentación bajo docs/- esto es lo que la gente esperaría.

Answer 7

Uso Apache Maven 2 y obtendrá todos los artefactos que necesita ... con un simple comando "mvn sitio de paquete"

Answer 8

Yo sugeriría SourceForge (http://sourceforge.net) para su proyecto de alojamiento, ya que tienen una amplia variedad de herramientas (blogging, wiki, opciones de control de fuente, etc.) y todo es gratis.

En cuanto a qué poner en el zip/jar ... realmente depende del tipo de proyecto. Si se trata de una biblioteca reutilizable, sugeriría que en la raíz del archivo, tenga su licencia y su jar de distribución. Puede colocar dependencias en un subdirectorio lib, con su documentación en un subdirectorio docs.

Un ejemplo probablemente lo ayude a mejorar ... descargue el API de Jakarta Commons - Lang (http://commons.apache.org/lang) y mire lo que ofrecen.

Una de las otras respuestas fue usar Maven (http://maven.apache.org) para administrar su proyecto y también lo recomendaría, aunque si no lo ha usado antes puede tener un poco de curva de aprendizaje del desarrollador.

Buena suerte y espero que esto ayude un poco.

Answer 9

Libro: Practical API Design Confessions of a Java Framework Architec t (Jaroslav Tulach, 2008, Apress).

Además de las sugerencias en el libro, por favor haga una documentación adecuada (comentarios, javadocs) e incluya muestras de uso en algún lugar público (preferiblemente en un estilo wiki). El uso puede ser obvio para los desarrolladores pero no para los clientes (consulte JFreeChart como ejemplo).