Lost in LoC

In one of my earlier posts I mentioned that for the past 7 years I primarily worked in the world of .NET.  I enjoyed those 7 years.  Microsoft’s .NET Framework is rich and fun to use.  The C# language continues to impress me as it matures, the Framework’s classes and libraries are intuitive to use, and the documentation, despite being about 2.5 gigs, is thorough, easy to understand, and complete.  As far as I’m concerned, Microsoft’s .NET Framework is a home run as far as frameworks go; it’s the big “Pro” when it comes to developing MS based applications.

That being said, there’s a lot of cons.  You pretty much have no choice but to use Windows.  You’re realistically stuck with having to use Microsoft’s flagship IDE, Visual Studio .NET.  Despite having fantastic integrated debugging, the IDE itself is very… Microsofty.  It’s very point and click.  The keyboard shortcuts aren’t very powerful (mouseless navigation is nearly impossible).  It’s expensive (if you’re not using one of the stripped down “free” versions). It’s bloated, slow, and buggy.  It crashes all the time.  It has very little support for Agile development, and what support there is completely misses the point (I’m looking at you, MSUnit).  I also think that VS.NET teaches novice developers how to do everything wrong (code-behind is a wickedly evil thing).  Overall, the entire thing really kinda sucks, and if it weren’t for ReSharper the thing would be almost useless.

About 2 months ago I started focusing hard on iPhone and Mac OS X software development.  One of the things I liked right off the bat was that I didn’t have to buy any development tools.  In fact, I didn’t even have to download anything because my Macbook Pro came with everything I needed to get going.  IDE for development? Check. Performance monitoring tools?  Check.  App for creating interfaces?  Check.  Incredibly impressed with the tools that come out of the box, ready for development (including Subversion, python, ruby, IDE’s and graphical tools)?  Check.  As far as development tools and “out of the box” readyness for somebody to get their geek on, Apple hit a home run.  This is Apple’s “Pro” entry.

Fast forward 2 months.  Ask me if I’m still developing my iPhone application.  Go on.  Ask.  I’m serious!  Do it!

Are you still developing your iPhone application?

Hell no.

Uh… why not?

Because despite having great tools out of the box (+1), the developer documentation is so horrendous that it artificially inflates the learning curve by a factor of 10 (-1 gazillion!).  Yes, there are oodles of example code at the Apple Developer site, and yes there are oodles of videos too.  That’s great if you already have a decent 5,000 foot view of the technological components you want to work with, but it sucks if you don’t have that 5,000 foot view.  And the only way to have that 5,000 foot view is if you’ve already been developing in Cocoa Framework for the past several years.

The problem is in the details, literally.  Their code examples demonstrate the raw intricacies of the how, but not the conceptual understanding of the what and why.  As a result I find it incredibly difficult to see the low level implementation details when I don’t have a decent understanding of the classes involved at a higher level.  At the other end of the spectrum are their videos.  These videos are 50,000 foot pie-in-the-sky views that give the audience a really casual understanding of general stuff.  They’re essentially marketing videos for nerds.  They’re great if you’re just getting started and you need a super-high level view of how the various frameworks piece together, but they don’t prepare you to actually do anything.

So what about the documentation that comes with the development tools?

A great question!  Let me take the Socratic method and answer your question with a question.  What documentation? Imagine, if you will, the horror of opening up the documentation tool for Xcode (an entirely separate application that helps you search and organize Apple’s documentation – good in theory, fails miserably in practice) and finding that the documentation for almost every single class and method is only 1 sentence long, and that 1 sentence is the most formal, computer-sciency idiomatic statement you can possibly imagine.  That’s Cocoa’s documentation.  The inline comments provided by the header files are better, but barely.

This has frustrated me on so many occasions that the euphoria I experienced while trying to develop my first iPhone application quickly turned into the searing pain of frustration and anger.  It frustrates me doubly so because Apple is a fantastic company with fantastic products for which I desperately want to contribute, but I can’t.  I have a limited amount of time every week that I reserve for Apple development, and their lack of documentation is completely counter productive.  I can easily spend the entire time searching for a snippet of easy to read, easy to understand documentation about, for example, what methods you have to implement in order for your class to act as a delegate to some other class.  The documentation just isn’t there, and if it is, it’s so horribly organized that I couldn’t find it if it jumped out and kicked me in the junk.

This brings me to the point which I eluded to in the title of this entry.  It’s great to have lots of fun, good looking, easy to use tools.  It’s great to sit down and hammer out oodles of code.  It’s super duper fun to compile your application and watch it run, crash, and burn.  Those are great skills to have, but the thing that really makes software development a joy is the same thing that makes almost any other traditional profession a joy:  clear communication.

I once met a kid in grade 10 that was a computer whiz, but was failing out of school because he refused to apply any of his efforts towards his non-technical, non-sciency classes.  At the top of this failure list was English.  I asked him why he didn’t like English.

Because it’s stupid.  I’m not going to use it!  I want to be a programmer, not an author!  I don’t care about that stuff!

Needless to say I had to inform him that a very large portion of my job is not writing code, but communicating complex ideas to other people.  People that are both tech-savy and technically-inept.  Communication is one of, if not the most important skill in software industry.  He was shocked.

I once had a job in which I was told, on my first day, that my responsibilities would be “to port application X into application Y”.  I asked where the requirements were and if I could have access because I will need to review those requirement in order to do the job.  I was told that there weren’t any requirements, and that I should just “read the code.”  Naturally the person who told me this was not a technical person, and I couldn’t get mad at them because as far as they knew reading code was just like reading a well written novel.  In reality, reading code is more like reading a very poorly written novel, in which there are either far too many or far too few characters, and all the pages are mixed up, and there are no page numbers, and all of a sudden it just ends.

For whatever reason, Apple has forgotten the importance of clear communication.  This is unfortunate because Apple is in a position in which they can take a significant dent out of Microsoft’s developer base if they wanted to.  Apple has all the fun sexy toys.  They have all the innovation.  They have all the trend and momentum right now.  Microsoft, conversely, has a failing strategy in almost every segment of the computer industry.  If Apple could deliver a rich, thorough, and well organized set of documentation for their Cocoa framework, it could be a huge blow to Microsoft’s developer strategy.  So far, though, Apple is completely dropping the ball.

Apple.  If you’re listening – get busy and floor me with some excellent documentation.

Readers.  If you’re willing – floor me with some excellent resources that tell me the what and why, and not the how of the Cocoa Framework.