Rainy days and Java always get me down

I've Moved My Blog

It's currently located at http://www.urlinone.com/blog

I should say "I'm moving my blog." It's a pretty painful process.

Pebble has blown up on me, and it's been many months since I've been able to blog reliably. I've lost posts. And now I've got to figure out how to migrate my past blog posts from Pebble to my new destination without all the URLs changing, lest external links become 404 Not Founds.

Why does everything in the 21st century have to be a three-day project???

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.

<p>Pretty cool. I like the cross cutting especially. I had two ideas. <p>(1) You could maintain your prose in a separate file, and then use inline comments of a specific format as a pseudo "cutpoint". <pre> // :Some doco token: Insert common documentation here. </pre> <p>Of couse, this would have to match the syntax of the file type. For xml it would be.. <!-- ... <p>But what about source that is not yours .... ? <p>(2) In your external documentation, you could use something similar to XPath to indicate where to apply the documentation. You could match accross packages, classes, methods, even use regular expressions to match various programming idioms. <p><p> On compiling it, you could do some pretty cool stuff taking off from java2html. You could do popup divs liked little postit notes, or if you wantted to get facny, you could even figure out a way to do an overlay on top of the source. <p>You may get stuck on line numbering, as an active project will render that obsolete in minutes.
Thanks for your feedback. It's good to know someone's out there. :-)<p>As far as #1 goes, I was assuming this would be used for source code <b>not</b> under the user's control (probably since I can't modify every file in AppFuse ;), so a recognizable token, while a great idea, is probably not practical. It's a shame, because it certainly would simplify things. Maybe that <i>could</i> be included as an option for those times when the developer is also doing the documentation. It would certainly offer benefits over the alternative.<p>As for #2, I like the idea of something XPath-ish. I've been playing with the idea of line-by-line checksums or CRCs, so you could try to find your context (or guess at it, in case the line you're interested in has changed). If it runs as an ant task, it could notify the developer when it encounters comments that it can no longer place, but it might still be able to guess at the vicinity where the comment used to belong.<p>I've been contemplating what can be done with Javascript and CSS. I like your ideas. Keep 'em coming!

Add a comment

HTML : b, i, blockquote, br, p, pre, a href="", ul, ol, li
E-mail address
Remember me Yes  No 

E-mail addresses are not publicly displayed, so please only leave your e-mail address if you would like to be notified when new comments are added to this blog entry (you can opt-out later).

TrackBack to http://www.leegrey.com/hmm/addTrackBack.action?entry=1089669626000