Personalized Data Mapping

Give me somewhere to stand, and I will move the earth.

Our mission is to take control of the desktop away from the major software manufacturers and put it in the hands of the world's independent software developers. The desktop has stagnated for fourteen years thanks to the reluctance of the major software manufacturers to introduce new designs in the interests of backward compatibility. It's time to change that.

To accomplish our mission, we are building a smart, visual, and autonomous information manager of all of a user's information, whether that information is data or programs, and whether it originates on the web, via mail, news, ftp, an editor, or any other application. It is not a search engine, browser, desktop, or operating system, although it shares elements of all four programs.

It is written in Java to make it portable across as many computers, operating systems, and browsers as possible, and it is free and open-source. Unlike other open-source projects like Gnu and Linux, however, to make it attractive to everyone it needs to be adaptive, autonomous, and visual from the start.

To make rapid change possible, it also needs to be well-written, flexible, extensively documented, easy to understand and modify, and easy to find and download from the web. Any Java programmer, anywhere on earth, should be able to extend it. If successful, it should lead to rapid improvements in user interfaces, adaptive agents, and information management schemes.

Building such an ambitious program with such a strong emphasis on software quality means building many subprograms, linking them together solely with well-designed interfaces, and creating an awful lot of documentation.

For the project to succeed, those programs, interfaces, and documents, plus the project as a whole, must have the following three properties:

* Flexibility: It doesn't matter how hard we work on the program if it isn't extensible.

Outside programmers must be able to easily modify our code to suit their own needs or to accommodate new extensions they develop.

Consequently, our program must be very flexible. It should be possible to alter its structure at runtime without having to stop and recompile the program as a whole.

As far as possible, no class, module, package, agent or any other portion of the program should have any knowledge whatsoever of any other portion of the program. Everything, starting all the way down at the method level, should be as encapsulated as possible. Flexibility is a high priority.
* Robustness: It doesn't matter how flexible it is if isn't trustworthy.

Outside programmers must have faith in our code's ability to do what its documentation says it does without inexplicable failures so that they can add new features without worrying that the whole thing will collapse.

Consequently, our program must be robust and self-validating, and all its parts must be bug-free. Using assertions for critical methods, validating inputs, programming defensively, and so on, are all critical qualities in producing quality code. Robustness is a high priority.
* Clarity: It doesn't matter how robust it is if it isn't readable.

Outside programmers must be able to understand our code easily---and understand it in detail---if they are to extend it for their own purposes.

Consequently, our documentation must be extensive, consistent, and exhaustive, starting from extensive in-line documentation, then class-level documentation, and on to package-level and project-level documentation, plus interaction diagrams for every level of code interaction.

A reasonably competent outside programmer should be able to spend at most a week reading the documentation and playing with the program to understand it all. It is better to provide too much documentation than too little, once it is well-written to begin with. Badly written documentation, no matter how extensive, will not communicate that the code was done by professionals and therefore will not inspire trust in the code. Clarity is a high priority.

In pursuit of these three goals we have to give other possible goals second place. First among them is efficiency (speed, memory use, storage use, code sharing, loop optimizing, and so on). This must be sacrificed, if necessary.

We all have a strong bias to produce the most efficient code possible and that is fine---code should always be as efficient as possible---but in pursuit of that we can't sacrifice flexibility (ability to reconfigure the architecture, even at the class level), robustness (strong resistance to bugs), and clarity (easily understood logical flow). Those three properties come first and foremost.

Once we have a flexible, stable, well-written program we can always worry about improving its efficiency later (or simply wait for faster machines).

Bottom Line: if in doubt about whether to use a fast, but tricky, inflexible, non-portable, hard to understand, or hard to modify piece of code versus one that may be slower or more memory intensive, but which is simple, flexible, portable, easy to understand, and easy to modify, always choose the latter.