garann means > totes profesh

a defunct web development blog

this self-documenting stuff is better in theory

Thu, 23 Oct 2008 17:28:13 +0000

I used to work in a Java shop where we had all kinds of documentation. We had a full-on API. It was very useful, and even in the cases where it needed a little updating, it helped you figure out where to begin looking for whatever you were looking for. I remember there was some fancy thing in Eclipse that would even create the javadoc code for you if you were willing to add a new method via some contrived WYSIWYG method. I've never worked with anything like that in .NET, but that's ok, it's pretty easy to work backward in the latest version of Visual Studio.

Javascript, to the best of my knowledge, lacks any 'Find All References' abilities no matter which editor you're using, and thus is a place I'd like to see more javadoc-style commenting. Any Javascript library spanning more than three files needs API documentation, or you're just going to end up rewriting what someone else wrote before. All for lack of documentation. The problem's exacerbated as it becomes more fashionable to move all Javascript off the page. Without good documentation, it can be nigh impossible to find out where script is called in those scenarios.

Apparently there's something called JSDoc which provides javadoc functionality for Javascript. It appears the results have all the visual appeal of javadocs, too. There's also something called HeaderDoc that I'm inclined to trust further because of the nice documentation and that fact that it's from Apple. (Terrible reason, I know, but if I weren't a sucker for a good interface I wouldn't be in this line of work.)

Looking for others..