Best practices for writing open source Java

Question

Where can I find some best practices for writing open source Java code? I'm not looking for directions on how to write the code proper, but rather on distribution, packaging, documentation, and all the other aspects besides .java files.

My goal is to take a module I've written and publish it as open source.

Edit - I'm still missing direct, concrete instructions on what the zip file should contain. Are there conventions for this, or should I just pick some reasonable structure?

Answer 1

See Karl Fogel's book http://producingoss.com/ - source available on-line.

Answer 2

I'm not sure if there will be universal agreement on "best practices", but the items you mention might have easy answers:

1. Distribution is easy with java.net or Sourceforge. You'll publish your code using their standards,
2. Packaging will be ZIP files. It's a good idea to create an MD5 hash to make it possible for clients to check the integrity of their downloads.
3. Documentation - yes, lots please. Have separate javadocs and a reference guide that shows how to use your stuff.
4. Have a public SVN that allows anonymous access so folks can get and build the latest code on their own.
5. Have a bug tracker that allows people to report on bugs, new features, etc.
6. Set up a wiki for discussion, feedback, etc.
7. Maven has become something of an open source standard. Have a good pom.xml for those adventurous folks who want to check out and build your code.
8. Unit tests and good code coverage will help to demonstrate your commitment to quality.

I'll try to think of more.

Answer 3

I think it all boils down to automating the build-test-package-deploy cycle. Ideally, you should be able to do it with a single click (or with a single prompt command).

Personally, I use ant and define a deploy target which does the following

1. Builds all artifacts
2. Packages the artifacts into a single deliverable (.zip file)
3. Unzips the .zip into a local directory
4. Runs the test suite from that local directory
5. Uploads the .zip onto sourceforge

Having done that the only manual step is to define a new release via sourceforge's web-site.

Obviously, in order to make this procedure effective you must be test infected - I write tests for every new feature I am implementing.

Answer 4

If you're looking for specific directory structures, why not look at existing open source projects? I'd start with Jakarta Commons, which is a heavily used package.

Without any statistics to back me up, I'd say that many projects use a directory structure similar to that specified by Maven, even if they don't use Maven itself (and if you can get past the Maven learning curve, it is a nice build tool 90% of the time).

Answer 5

I am not adding that much, but I would suggest the following:

Directory structure

• Try to make the javadocs complete, most open source modules or libraries don't have many javadoc comments. Generate the javadocs documentation and place it in a directory such as apidocs. If applicable in the javadocs, you should specify who is allow to call a class and in which circumstances the class/function should be called. Small code examples also don't hurt and are worth adding.
• Add an "examples" directory to help the developers/users use/integrate your module.
• Add a license files at the root of your directory structure and ensure that each of your file has a license header.
• Add a README file at the root directory of the distribution for general information and/or specifics(link to the software, author, help and support, installation instructions, etc.)
• Usually the source code goes into an src directories and the documentation goes into a docs folder.

Packaging

• Try distributing your software into appropriate formats(zip, tar.gz, dmg, exe, jar, etc.). For example for a web application, I would have a zip, tar.gz, a war and maybe an ear. Depending on the website you'll be uploading to, you might be required to use an archive format such as zip.
• Create an installer if applicable or not too tedious

Publishing

• Follow the instructions if applicable to upload your module.

• Advertise your module(Blog, Forums, Twitter, etc.)

  Always make additional tests when packaging or uploading, something unexpected could occur(missing file, archive corruption, etc.).

Answer 6

If your project is named Foo, then version X.Y should be packaged in Foo-X.Y.zip and unzip to Foo-X.Y/.... (in other words, the path of each file in the archive should start with Foo-X.Y/)

Have a Foo-X.Y/README.txt containing basic instructions as a plain text file. It should at least contain information about where the full documentation is ("see docs/index.html for documentation") as well as brief instructions about usage ("add lib/Foo-X.Y.jar to your classpath") and rebuild instructions ("run "ant build" to regenerate libraries in lib and javadoc in apidoc/").

If your project requires additional libraries to work or compile, then automate that. I.e. either let this be a Maven project or ensure it works with Ant Ivy.

I would suggest having the source under src/, the built libraries under lib/, the documentation under docs/ - this is what people would expect.

Answer 7

Use Apache Maven 2 and you will get all the artifacts you need... with a simple command "mvn package site"

Answer 8

I would suggest SourceForge (http://sourceforge.net) for your project hosting as they have a wide variety of tools (blogging, wiki, source control options, etc) and it's all free.

As far as what to put in the zip/jar... it really depends on the type of project. If it's a reusable library, I would suggest that in the root of the archive, have your license, and your distribution jar. You could put dependencies in a lib sub-directory, with your documentation in a docs subdirectory.

An example would probably help you better... download the Jakarta Commons - Lang API (http://commons.apache.org/lang) and look at what they provide.

One of the other answers was to use Maven (http://maven.apache.org) to manage your project and I would also recommend this, though if you haven't used it before it can have a bit of developer learning curve.

Good luck and I hope this helps a little.

Answer 9

Book: Practical API Design Confessions of a Java Framework Architect (Jaroslav Tulach, 2008, Apress).

Besides the hints in the book, please do a proper documentation (comments, javadocs) and include usage samples somewhere public (preferrably in a wiki style). Usage might be obvious to the devs but not for the clients (See JFreeChart as an example).