Friday, November 14, 2008

Blogging is hard!

Two months and only two posts. I'm not sure what I was thinking when I started this blog but I was certainly hoping to be more prolific than this. In retrospect I'm not sure why I had this expectation: I never finished my dissertation in grad school and I never published any of my research papers. The problem is that once you've done the research, had the idea or experience that is the germ of an essay, it's over and done with. Why revisit it to try and tease out clearly communicable thoughts to communicate to others, time to move on to something else new and shiny.

This is the great allure of programming to me -- you can have an idea, code it, debug it and ship it without having to explain it. Explaining something takes far too long and even then it's unlikely that your audience has understood your message. Writing is hard, very hard. These missives are meant to be short and to the point (unless you are Steve Yegge.. but his blogs ARE short and to the point, it's just that the point is really a very thick novel.)

Speaking of the point, I did have one... let's see, ah yes... Blogging is hard, very hard. It's hard because it's easier to go design a new feature and code it or to verbally market that same feature in a product meeting than it is to clearly explain that feature and document it in written human language. Coding allows you to be precise; even if you are a newbie or don't know what you are doing and are not keeping it simple and don't have clear requirements you can create a mangled method of some kind that works -- it will compile and run (and if you actually are smart enough to use TDD, it will pass your tests.) You get some sort of external validation and thus gratification on your creativity immediately. The same holds true for verbal explication; you can expound ad naseum and even if you've lost focus and shifted gears several times, if you speak with animation, conviction and passion you will be believed and will either sell your idea or at least what your audience PERCEIVES as your idea.

Unfortunately writing, especially the combination of succinct reportage and witty column that typifies the best blogging, is much more challenging. Not only do you have to force yourself to hit the keyboard and actually delve into your thoughts, but then you have to attempt to make it interesting and esthetically pleasing. The hell with that -- I'm going to go code, the compiler while it is judgemental is easily pacified... an external audience that cannot be browbeat or seen is much more frightening. But I want to get better at writing and I want to engage a wider audience so I can become a better professional and perhaps a better person. So instead of having an idea and then abandoning it either before starting to write a blog or giving up after jotting down hundreds of ill-fitting and awkward words that cry out for editing, I'm going to try to just post something -- at least once a week, if not more frequently. So when I have a rant about something I encounter, like my post about API docs yesterday, I'm just going to put it out here. Hopefully I'll get better over time, but instead of puttering away on half-finished, never-ending posts I am moving the suffering out to whoever reads this and resolving to just post. Enjoy.

Read more »

Wednesday, November 12, 2008

Generating API Docs and the Relative Decline of MS developer tools

Three years ago, when I left the Microsoft/.NET development world for the wilds of J2EE/JEE and the confusing alphabet soup of standards, JSRs, JEE server implementations, etc.  I was expecting poorer quality development tools, much harder to configure servers, and a nightmare of database adminsitration and sub-standard drivers.   A couple months ago I returned to the MS world.  I thought it was just me having a hard time re-adjusting -- .NET 2.0 (and now 3.5) and C# 2.0 and 3.0 are more nuanced and complex than .NET 1.1 and C# used to be.   But I've had my off-on-the-road to Damascus (yes, I'm mixing references badly) moment. Microsoft is increasingly going to lose developers to Java and Ruby and other platforms and toolsets that are easier to use, cheaper (free as in beer) and far less proprietary in scope.

The catalyst for my epiphany was trying to generate some simple html API docs for a couple of our larger assemblies at work.  In Ruby or Java or Perl this is pretty simply done -- point a configuration task (i.e. in ant or maven or in code) at the project/module/package and very quickly voila, a set of JavaDoc based html documentation based on the structure of the code and the annotation comments on methods and classes.  In the last few versions of Eclipse you just select Project | Generate JavaDocs  and select a location and in a few SECONDS you get simple API docs in HTML that are easily added to source control, can be diffed, put on just about any sort of wiki or website, etc.

So how does Microsoft with their expensive Visual Studio and their proprietary advantage generate .NetDocs?  They don't.  To be fair there is the built in ability for compilation to generate XML documentation based on the /// comments in the code.  But there is NO built in mechanism to generate API docs.  With Visual Studio 2002 and 2003 there was an open source project called NDoc which generated html API from these comments and integretated into Visual Studio and ran fairly slowly.  But it is no longer maintained.  For .NET 2.0 and newer (3.0 and 3.5 and soon 4.0) there is an open source project from Microsoft called SandCastle.  It generates really good looking .chm (compiled HTML help) documentation but does NOT integrate at all with Visual Studio.  I couldn't get it working until an answer on pointed to a blog posting that ran me through it.  Even though it does generate HTML, it is really aimed at creating .chm files which are binary.  You have to run a separate tool outside of the IDE to create this documentation and it takes forever (this is because it has to actually connect to MSDN to get some .NET dependency documenation because the .NET core libraries are not open). So something that works quickly and is much easier to set up and use with a FREE IDE and is cross-platform is much harder to setup, doesn't work as usefully and is not integrated well with the EXPENSIVE proprietary tools from Microsoft.  

Yes API Docs are not very important in terms of overall development tools and functionality.  But this pattern is repeated throughout the Microsoft toolset (with the possible exception of SQL server -- the 2008 version of the Management Studio is incredible!) To get better (read useable) refactoring and getter/setter generation for Visual Studio (so you don't have to type lots of boiler plate code) developers in the know buy ReSharper.  Nothing wrong with that, it's a great tool BUT it galls me to buy an IDE then buy add-ins for it when you get the same functionality for free with Eclipse (and NetBeans and so on).  When MS developers realize that developers on other platforms have as good or better tools and they don't have to pay for them, no wonder they be less enthusiastic about MS.

I could keep ranting about the alphabet soup of extensions and versions and platforms from Microsoft but I won't.  MS has historically made the best tools for both rapid development and for robust Windows development, tools that were the envy of developers on other OS and platforms.  That's not true anymore and I think MS will pay the price in terms of lost developers.

Read more »