Tip<Java>: Learning to use open-source Java library

Just looking at , there are no lack of excellent open-source projects to choose from.  The site contains a large repository of open-source projects ever conceived.  There are many interesting projects comprising application and library that one can download and use it subjected to the open-source license like GPL, LGPL. In this post, the focus is on learning how to use a class library particularly those that are poorly supported by its documentation. A class library is basically contains a series of files that comprises of reusable classes and components that exposed through its API (Application Programming Interface eg function, variable, class) that can be used to create a application.

Some of my favourite open-source libraries are JFreeChart , iText , , , H2Database . These are very prominent open-source projects that are well-documented with excellent support by its authors and book publishers as well. JFreeChart is supported with a very comprehensive well-written commercial ebook that no serious JFreeChart developers should be without, iText and HttpClient  are complemented with books from Manning , Oreilly  

 

However these are by no means the only libraries that are useful as these popular libraries are very specialized in its usage and application. There are alternatives to these libraries that varies in term of sophistication and size, and also libraries that perform other functions like 3d rendering libraries, printing, OLAP, XML and JSON processing.

Anyone wanna guess what the following class does ?

As much as open-source libraries are well-known for their innovativeness and usefulness, majority of them tend to suffer from lack of documentation, support and examples which prohibit their widespread use. Usually, the libraries only come with sparse  documentation and examples for good start but developers are helpless once they want to tap the full capabilities of the library. In addition, most libraries simply generate the API in JavaDoc (left) with hardly any explanation of what a class or method does. This usually due to the fact that library authors generally do not like to write documentation as they prefer to engage in coding and subscribe to the ‘fallacy’ that code itself is the best form of documentation which quite ironically given that the examples that come with library hardly are that comprehensive. Indeed, most libraries often assume one to have a ‘hacking’ mentality to delve into codebase to understand how the library can be used. There are no end to number of innovative open-source projects that will have received much deserved attention and usage with the potential to be the ‘next big library’ have it not for their lacklustre documentation and support by their author. Most open-source library project authors seems to harbour the thought that if they build it, developers will use it base on merit of quality and innovativeness of the library. Little did he thought that often it is often the ‘dull documentation’ that most open-source authors ignored that ultimately determine the fate of the project. Most developers will not have much patience exploring the library if there are other alternative libraries with much better documentation and support.  Once a while with some luck, project with poor doc and support becomes overwhelming successful, but still let’s not bet on it.

Some experienced open-source library developers like the author of H2Database  (embedded database), truly understand that good documentation and support are keys to acceptance especially where competition is intense (eg Java6 includes a official embedded database, Derby. HSQLDB, ironically the database the author develop himself, is a direct competitor too ) something that he had learnt and applied due to past endeavour (Before that, he developed the HSQLDB   the popular embedded database that bundles with some open-source projects eg  , a excellent web framework). It is a good example that shows passion alone could not ensure the success of a open-source project, and it really takes a lot of commitment and discipline to do mundane unpopular tasks (eg writing unit-test, documentation, forum support) that is important to survival of the project.

 

So given these circumstances where poor documentation and support are the norm rather than exception, how can a developer learn to use a class library ? The following offers some checklists that developer can use as a guide.

• User’s Guide/Documentation – Usually comes together as part of compressed downloaded library file. They are popularly distributed in PDF or html files. They usually offer good introduction on the library, setup and rudimentary usage to get started. They cover the important area but does not offer much depth (There always exception, JGraph offers one of the best open-source project documentations). Perhaps one plausible reason that documentation seems lacking is due to involving effort requires to update it especially if the library is still undergoing changes (Library hardly ever get finalized). And because of changes (especially API changes) that never seem to get “freeze”, it unfortunately becomes a recurring excuse for not putting effort in providing good documentation.
  
• Book - If you can get to learn and understand a library from a book, why not ? The book usually goes through rounds of editing and proofreading by professionals from book publishing firms to ensure quality and readability are maintained (Not to say that all books are erroneous)
  
• Example codes – Generally contains example codes that cover wide range of functions. They are usually short and demonstrated specific function of the library.
  
• unit-test codes – This is often over-looked but is one of the most effective way to learn and unlock the usage of the library.  Take note that these codes usually do not come with the binary download of library but as source code version of the library as the test-codes can be quite large. These are often found in their own test directory and perform comprehensive testing of crucial classes. One major problem in using a library is how to use the class and its API, and how it can be used appropriately. From these testing codes, one can learn how to use the API and classes. In fact, some libraries do use the test code to demonstrate the usage of API of the library extensively. Check out   and see how its unit-test codes teach one to use its API. The following shows the fragment of the test-codes. Notice how the API is been used.
  
  
• Open-source Project – Most open-source projects, whether application or library, actually leverage heavily on open-source resources too. It means that someone has learnt to use the library and apply it into his project and therefore checking out the source code might shred some light on how the library and its API are been used. But how does one find out whether respective library is been used ? The answer is to make use of Open Source Code Search Engine likes , , a search engine that specializes in searching source code by offering advanced and management tools. For example, just enter the keyword that belong to the library, and the search engine returns a list of projects that use the library.

  
  

• Wiki, forum, support site, mailing list – These are popular places where one can find answer and support for the library. But whether one find those effective, I leave the answer to you.
• JavaDoc – These are information generated by those JavaDoc ‘comment’ within the source code. It contains description on the method, variable and classes. In the past, producing informative JavaDoc can be a hinder as it can makes code navigation cumbersome (long comment requires more keystrokes, scrolling), however these are no longer viable excuses as modern IDE are capable of folding (hiding) comment to make code navigation easier.
  From this
  
  to this
  

About these ads