Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this 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?
I'm not sure if there will be universal agreement on "best practices", but the items you mention might have easy answers:
Distribution is easy with java.net or Sourceforge. You'll publish your code using their standards,
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.
Documentation - yes, lots please. Have separate javadocs and a reference guide that shows how to use your stuff.
Have a public SVN that allows anonymous access so folks can get and build the latest code on their own.
Have a bug tracker that allows people to report on bugs, new features, etc.
Set up a wiki for discussion, feedback, etc.
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.
Unit tests and good code coverage will help to demonstrate your commitment to quality.
I'll try to think of more.
See Karl Fogel's book http://producingoss.com/ - source available on-line.
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).
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.).
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
Builds all artifacts
Packages the artifacts into a single deliverable (.zip file)
Unzips the .zip into a local directory
Runs the test suite from that local directory
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.
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.
Use Apache Maven 2 and you will get all the artifacts you need... with a simple command "mvn package site"
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.
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).
Related
I want to get started with Java! I have a bit of experience with C/C++ and Python development. For this i'm mainly using Emacs (a text editor) and the commandline, thus not using a heavier weight IDE for those kind of things.
I don't want to adapt my workflow to suit an IDE, but I don't know the Workflow (write, build, test) in Java so I thought about asking here. Searching the Web didn't give me good results.
Can someone give me the the basic workflow when developing Java with my requirements? I use Linux for all my programming.
Are my requirements/wishes even practical or should i consider using something like IDEA or Eclipse?
Can someone point me to documentation or blog posts about this topic or documents, that give a quick overview and/or examples on how to get started with Java (something for programmers with a little experience in other languages)?
For this I'm mainly using Emacs (a text editor) and the commandline,
thus not using a heavier weight IDE for those kind of things.
An IDE has many advantages over a text editor, mainly when navigating, debugging and refactoring code, but it is not required. Actually, working without an IDE is useful to understand the underlying technologies. My advice would be: Start without an IDE, and when everything works, try out some IDEs to see how they help you.
Can someone give me the the basic workflow when developing Java with
my requirements?
The basic workflow is (for any compiled language):
write source code
build
run
In the case of Java, that means:
1 Writing source code
You write .java files in a text editor, observing the right filesystem layout (file name = class name, directory corresponds to package etc.). You already have that covered.
2 Compiling the code
You compile the code using a Java compiler, possibly building a JAR or WAR file (depending on the type of application you are writing). You can do that manually by directly invoking javac (see for example Java - compile from command line - external jar ), but you should really use a build tool. The best tool to get started is probably Apache Maven or Gradle.
The basic idea is the same with both Maven and Gradle: You write a build file, which essentially describes your project and how to compile it (a POM file in the case of Maven, a build.xml for Gradle), then you can build by just invoking the build tool. The build tool takes care of all the nitty gritty like invoking javac etc. Most importantly, both also perform dependency resolution, meaning they can automatically download and use libraries that you use in your code.
3 Running
Finally, you run the program from the command line. How to do that depends on the type of program: A simple executable (or a Spring Boot application) can by run using java -jar myprog.jar, a WAR file must be deployed to a Servlet container (such as Apache Tomcat).
I hope this gives a general overview of How do I develop without an IDE?. For more details, look for specific questions here on Stackoverflow (or elsewhere), read the docs, and if all fails ask a more specific question here :-).
I agree with #sleske : if you really want to learn the language, it's good to start with a text editor. Later on you can use an IDE but by then you will know how the build process works and what exactly the IDE is doing. There exists no magic in coding. If something works but you don't understand why, it will certainly fail one day :)
Maybe some nice feature: I use Eclipse and added a vim plugin :)
And if you learn some useful shortcuts you can write code really fast (without a mouse)
You should download IntelliJ directly:
certain best practices like static import make your code more readable because you read it with a smart IDE. If you read code just with vim, the navigation between classes is not possible.
you have an easy access to a terminal and perform certain Maven or Gradle commands here.
I would not say the same with other languages (css, html).
Say I implement an algorithm for a project. Say I want the same code to be used on another project. What would be the approach to do so? Just copy and paste code? Create a "library" project? What? Is there a tutorial or site that explains how to do this?
Sure, add it to a library project, but the benefit of reuse should always be compared to the cost of making the code general. Sure if you improve the code by fixing a bug or increasing performance, it is nice to get that into all projects where you use the code, but it also makes you slower because you have to keep the library compatible with all clients (at least the ones that will build after a breaking change).
It is often better to copy and adapt solutions to new projects, than to maintain far more complex solutions. One very important thing to take into account is how many client you think you will have for the library. How much work would it be to maintain those clients separately?
On the other hand some code is generic by nature and can most definitely be shared in a library to make your life easier.
If your algorithm is in Java, build it as a jar.
Then create a folder called "libs" in the root directory of your android project. Copy your jar into that folder. In eclipse go to
-> Properties -> Java Build Path
Under tab "Libraries", add your jar.
Now you can use your code.
You can as well link it with multiple projects.
If your algorithm is in natice C/C++, follow
http://marakana.com/s/introduction_to_ndk,1153/index.html
If you have a class/set of classes generic enough to be reutilizable, the solution would be separating them to a different project.
In your IDE, make your projects use the generic project as part of their build path (it is more flexible than including a jar).
When deploying, package all the generic classes in a jar and it to your solution. Don't forget to include that jar in the classpath.
In Java, there is no difference between "main project" and "library", other than the "library" usually does not include any main method (but it is not forbidden). They are classes in the classpath.
I'm looking for an update library for the software I am developing. It's a small software, but I'd like to imbue it with some nice features. One of those is auto-update. I've developed 2 class library to do this job for me, but I'd like a more robust library, becuase it's missing some features. Between the features the library could have, these could be in it:
Generate a difference file based on the old version (jar for example). Given the current version of the jar, and the new jar file, generate a new jar that will be downloaded by the clients, puting only the files that were changed since the last update.
Check some kind of checksum. Each file inside the JAR have it's own checksum, or the whole jar having a checksum.
Generate those checksum. If possible, while attending to the first item. File by file, or jar by jar, given the new files.
It would be nice if it could deal also if the input is a folder or a jar.
Merge the current jar with the downloaded one.
P.S.: I'm not writing a web-based (that runs in a browser) application.
Thanks for the attention.
Found the perfect solution for my needs in this answer: java web start alternative
Please take a look at this software https://code.google.com/p/getdown/ It claims it can be GCJ and be used to update also non-Java applications. But this does fills my expectations!
There are many possible ways of doing that. In fact, you already pointed what you need. While developing such a solution isn't a big deal, there are also many libraries and products that already do that.
Some examples are already stated in similar questions, like:
Autoupdate Feature in a Java Swing Desktop App
or
Design of auto-updating software
One example, out of a simple google web search is Autoupdate+
One thing to remember is that the install/update software doesn't necessarily need to be written in Java itself...
I was trying to get started with using (not making contributions to) the geotools lib yesterday,but i ended up trying to figure out what purpose does maven serve when it comes to someone that just wants to build a small/medium app based on geotools;At first i thought that using maven spares the dev on writing all the imports ( that's what i recon dependencies are BTW) but after reading a blog that had a somewhat modified version of the quickstart tutorial i'm not that sure anymore..Could someone make clarify what is maven's use for someone that just wants to build some apps and not make contributions?
Maven has nothing to do with saving you from import declarations in Java source files. It is about handling your whole project and that might include dependencies. But you still have to write imports in Java. If your project is to small for maven to be useful, don't use it. But in larger project a declarative build description, dependency management tool is definitely useful.
I wouldn't attempt to use the GeoTools library without Maven, it is a large and quite complex project with 10s of jars. Your app will probably only need 5-10 of those jars but without Maven it is almost impossible to work out which 5-10 you'll need. For example you will probably want to read in some data, so you'll need gt-data and at least one specific datastore gt-shapefile or gt-postgis. I'm pretty sure one of those will need to use a coordinate system so gt-referencing (and a specific implementation, say gt-epsg-hsql).
Anyway you should probably work through at least the quick start tutorial to see what Maven does for you.
I've had several classes - university level - on Java.
However, what these classes lack is some practical approach to Java - or, to programming as a whole. Things you can only learn in a business.
However, since I am not allowed to use Java on the workfloor, I don't get to learn this now - even though I would like to.
So I guess what I'm asking for is any number of plain have-to-know Java resources. Things concering, for example, what Ant is and why and how to use it; using revision control systems from your IDE; standard Java libraries you would use often ... Anything that would help with actual software development, really.
As some side information, I've been using Eclipse for about four years now, and I feel at home there.
I have a system that works fairly well for class assignments and for projects as well. Firstly, I create one Eclipse project per class. This way I can re-use classes from previous assignments. You can also customize your classpath by adding another project as a library.
I use the Maven plugin for Eclipse M2Eclipse. Not only does this give you the ability to search for libraries and add them easily but the exec:java plugin is an easy way to execute your code from the command line. It's helpful because when it executes your code, it uses a classpath that includes all linked Maven dependencies. If you aren't using external libraries, you might not need Maven but I've found it to be helpful to learn in preparation for the job market. It's fairly simple to start with plus there are a ton useful plugins for open source projects.
Next, for revision control I recommend Subclipse. You can get a free SVN account with a single login from Unfuddle.com. Link that up to your Eclipse environment and Import your project.
When I want to get a particular class specification, I go to Sun's Java documentation.
Another excellent resource that will certainly give you the reference material (searchable!) to answer any java question would be this torrent containing ~100 ebooks on Java, sorted by directory on various topics (like Ant, Eclipse, or Swing).