this self-documenting stuff is better in theory

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..


0 Responses to “this self-documenting stuff is better in theory”

  1. Leave a Comment

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

RSS Recent posts on the live version of this blog

  • An error has occurred; the feed is probably down. Try again later.

%d bloggers like this: