It occurred to me a couple of weeks ago that it would be very helpful to have a directory-by-directory, file-by-file, line-by-line description of what's happening within AppFuse. A wise man once advised me "if you can't find what you seek, become it." (I don't recall seeking an overworked, underpaid Java programmer, but I became one anyway.) I thought I might be able to give something back by taking on this project myself. I knew I'd learn a whole lot in the process, too. And future AppFuse users would certainly benefit from the effort. (Assuming my information is accurate, so… 😉
I documented a couple of files using a prose description, but I was not happy with the result. I'm not sure how clear or useful my ramblings really are. Through my dissatisfaction, though, I started to formulate a vision of how I would like to present this information in a useful and accessible way. The vision of what this is is still taking shape, but I've got a half-baked prototype done.
What I started to write yesterday is a semi-automated system to assist in documenting a software project so that visitors get the layout, the moving parts, and the details. I copied the basic Javadoc paradigm, but have repurposed it to be oriented around directory, file, and line documentation.
If you're wondering what's wrong with comments in files, I guess you could think of this as Aspect-Oriented Documentation. I'm trying to document down a different axis or dimension, so that you can see how the source files interact as a whole application, rather than at the standard programmer's comment level. You wouldn't put the kinds of comments into your code that I'm talking about putting in here. But for someone coming onto a project, this is the kind of information that they would want in a form that is highly available. It goes from a high-level description of what each directory holds, down to what the purpose of each file is, all the way down to what each stanza of code is for. While you may include pieces of this information within your files (and Javadoc), this entire presentation is intended to illustrate the big picture. If regular comments tell "how," these are more about "why."
This is very, very, very, very early stuff. I spent a day on it, and I'm still unsure where I'm heading exactly. The scope and intent changes every time I revisit it. I'm trying to decide on the UI for both the developer/documenter, as well as the viewer. I'm also unsure how to manage the information, especially on a growing, changing project. There is no choice but to externalize the commentary from the source, but keeping it associated with the right directory, file, and line(s) could prove challenging as the project progresses.
Could this evolve into a worthwhile general-purpose project? I'm not sure. I'm going to document AppFuse while I expand "AOD" and see where it leads. It would have been really poetic to be able to use AppFuse to document itself, but it just wasn't a fit. Maybe in the rewrite.
Here's a peek at the output from Line-by-Line. There's no documentation included at the time of this writing, but I already like it as a quick way to flip through the sources. I only wish it had the pretty print capabilities of java2html (and xml2html, properties2html, jsp2html, etc.).
I welcome your feedback on the idea, the implementation, the AppFuse content (once I've added some), etc.