Mike Duigou's Blog

Complexity

On April 21st the JXTA Community will turn three years old. The "terrible twos" weren't actually too terrible and the future of JXTA looks really, really exciting. The JXTA project has gone through a lot of changes over the last three years and it's been really interesting to see how the technology has evolved. The coolest part is, of course, that the path evolution has taken has been entirely unpredictable. I've decided to devote my first couple of blogs to some of the issues we've encountered in developing JXTA and perhaps there might be some insights for developing evolving technologies.

Complexity Is The Enemy

New users to JXTA often complain that it is too complex. I don't agree, but then again I am one of the primary JXTA authors. It is very possible that I am entirely biased. As a programmer I do often use other people's APIs and I do find some of them to be too complex. I have been doing a lot of security work lately with the Java JCE and often I swear (occasionally literally) that the Java JCE APIs are themselves encrypted!

Over the years I've encountered a number of APIs or libraries that left me befuddled on first exposure. In many cases I've needed to continue using APIs that had me stymied because my application needed the functionality. In some cases time and experience changed my opinions.

What could make JXTA or any technology complicated for new users? There are far too many possibilities:

• Installation hell - You want to use the API or technology, but before you can begin you need to decipher the website and download the right installer, install component XYZ and set your classpath to ABC and so on. Since you are new to the technology you can't be certain that you have installed it correctly. Oh well, hope for the best and press on.
• Configuration hell - It's not enough that I had trouble installing the technology, but now before using it you are required to configure it. What should I set MAX_THRESHOLD_INTERVAL to? How about CONTROL_PATH? Hmmm, I'm not yet even sure what these parameters are for let alone what values are permitted or what values should be used. Maybe I'll just stick with the defaults, hope for the best and press on.
• Starting hell - The technology seems to be installed, I hope, and seems to be configured, I hope, so its time to start using it. Hmmm, what do I do to start it? No, that's not it. Ummm, well that sort of worked, but there are a couple of messages I don't understand. Maybe the configuration isn't correct or maybe I ran the wrong command.... perhaps the documentation will provide some insight.
• Documentation hell - What? No manual! How about a FAQ or a Wiki? Hmmm... these entries seem all to be completely out of date. Or are they? This one says that in version 1.3 the database file must be in the home directory. I don't remember the installer mentioning a database file. Maybe I don't need one. Oh, there's an example. Hmmm, it's just "Hello World" and doesn't actually do anything. Oh, and it doesn't even run. Maybe I will look at the Javadocs. Ick! Most methods are missing all docs. None of the methods specify the behaviour or performance characteristics. Oh this is wretched.
• API hell - I sort of mentioned this one in the last blog and I'll mention it again in my next blog. When you start working with a new technology you are confronted with a vast seemingly featureless wall of API calls. Which ones do you start with? Are some preferred to others? How do I create a sub-class for a class that has 200 methods? (I recently had to make my first Swing component, a sub-class of JComboBox. I may one day recover from the experience). Perhaps most importantly, how do I begin architecting an application out of 80 classes and 500 methods that I have never used?
• More hells - The preceding were only a sample.... yes, sadly, only a sample. A truly devious technology could add support hell (in which all pleas for help go unanswered and you can find no-one to ask your questions), web hell (in which you are flooded by millions of pages of generic material all of which is obsolete), reliability hell (in which things only sometimes work and you never know why) and so on infinitely.

There are clearly a lot of hells in which the the poor developer can find themselves. Even Dante would probably have difficulty coming up with descriptions and purposes for all of them. And yet, software does get written. There are must be coping strategies for dealing with the complexity which abounds.

Scaling the wall

Different people attack a new complex technology using different approaches. Some people prefer to start with a working sample program and then radically refactor it step by step until it becomes their application. Other people insist on reading an entire book or a whole lot of web sites to gain perspective and broader understanding before starting. Still others will write a number of small test programs to develop an understanding.

My personal approach is more about finding out how the functionality behaves rather than just getting the syntax right. I'll run a program from the first moment it compiles just to see how it breaks or so that I can single step through it in the debugger. Once I think I understand how things work together I can usually make progress.

Easy is hard, hard is easy

There has been a lot of discussion lately about the usability of open source software. See ESR's The Luxury of Ignorance : An Open-Source Horror Story and an article I liked responding to ESR's article Ronco Spray-on Usability. A lot of the summary is that while most open source software isn't actually bad the authors do not seem to have spent a lot of effort on keeping it simple. A number of times the equation "If I can write five features that only one person can use in the time it takes me to write one feature everyone can use why would I penalize that one person?" seems to come up in the discussion. This is a total fallacy of course in that the maximum value of one person times five features is always five whereas the maximum value of one features times everyone is infinite. The equation is right in one thing, there may be a cost in quantity of features in order to achieve quality of features.

It's your problem too

In order for a product or technology to be successful the developers must provide some form of support. What obligations does a technology user have? When does it cease to be solely the original developers fault that a technology is too complex and start to become a shared shame?

First off, if you start working with a new open source technology plan right from the start to become a contributor. You are beginging the process of becoming an expert on the technology as a result of your using it. Given time you will find many ways, perhaps small at first, to improve the technology. On one project to which I have contributed to my entire contribution is a single word, "relative". However, it's carefully placed and makes the usage of a key API much more obvious.

Second, whether the project is open source or not, submit bugs. Something wrong or not clear? Submit a bug. If it seems after six months that the bugs are simply going into a black hole then perhaps you can stop (this will also be a good sign that its time to consider an alternate technology). Good projects respond to bugs.

Third, share your "Eureka" moments. People who have been using a technology for while usually forget what was hard for them when they started using the technology. If you suddenly say "A-ha", then share your realization. It may be the crucial insight some other struggling fellow user is missing. Or it may remind one of the "pros" of something that could be more clear. Or, and it does happen even for very mature technologies, it may be an insight that has never occurred to anyone else before. There's a great article on the history of the "ping" command in which the author admits to being very jealous of a user who figured out how to do something he (the expert and author) hadn't considered.

Fourth, take the time to share your knowledge, but also make it better for everyone. If there's a forum or mailing list you are reading to assist with your understanding then be sure to contribute back to it. Better yet, add your answer to the FAQ or the wiki. If the answer points to a needed improvement in the technology, then file a bug too. Best yet, submit a patch which makes the problem never re-occur.

Fifth, be an expert. Your experience extends beyond the single technology in question. Undoubtably your perspective on the technology and its' relationship to other technologies is unique and that's valuable. Take the opportunity to pontificate (a blog perhaps?) and share your opinion.

Comments

• Sharing knowledge
  As soon as I figure out how to use the wiki, I'll post my newly found knowledge about JXTA.

  Posted by: joconner on April 21, 2004 at 09:35 AM

This work is licensed under a Creative Commons License.