In the good ole days, if we hit an error message, we’d just write to the console a routine insult to the user.

If input_arg<0 then Print “You are such a dumb ass”

We now hide our contempt in secret code

If input_arg<0 then Print “Please contact your administrator”
/* You are such a dumb ass */

Sometimes we prefer the “I’m smarter than the runtime” pattern and send developers on a goose chase.

It is important to comment your code for maintenance developers benefit.

//instantiate object
Foo fooObject = new Foo();

This is important because, maintenance developers are unlikely to recognize the most common single line code pattern in object oriented development.

//call a method in the class
fooObject.SomeMethod(1,2,3);

This likewise is important because maintenance developers are unlikely to grasp the principle of methods and invocations.

//I’m smart and you’re stupid.

This is important because any maintenance developer that doesn’t grasp object instantiation and method invocation probably will need to be explicitly filled in on your utter lack of respect.

Keep in mind, that according to accurately compiled statistics, 61%* of all code will be debugged and maintained by the original developer.

Because 3 is a magic number.

You are a maintenence developer, you have been tasked to write foobar(), an incredibly useful function that was left out by the original developers.

1. Figure out how authorization works.

WMI. Relies on barely discoverable magic words (Namespace paths). Uses SQL as metaphor, but doesn’t actually have a proper database or relational structure behind it.

ADSI. Incomprehensible. Can’t easily play around with it as local authentication stores don’t act like active directory. And mere developers don’t usually have rights to Active Directory. Hence, no path to gaining competence.

Win32. Not friendly to languages other than C++. Incomprehensible.

Crypto API. Incomprehensible.

Javascript. Generally undiscoverable, but getting better with some IDE’s.

API’s that are better

COM, when early bound. Examples, ADO classic. Somewhat discoverable. When late bound relies on barely discoverable magic words (construction strings, method calls). Not friendly to languages that weren’t built specifically to be COM friendly.

WSDL Web Services. Not friendly unless you are using tools that ‘do it all for you’

API’s I like

REST. Plays very well with all programming languages that can make a GET request and receive an HTTP response.

.NET Framework. Highly discoverable, documentation strategy is build into the framework.

Patterns

• Discoverable metadata. APIs that could support intellisense if the IDE supported it are good. APIs that make it too hard for IDE’s to support intellisense are bad.
• Independent. APIs that have a fierce registration burden—I don’t like.
• Built in documentation. APIs should have javadoc type documentation features
• Aspect Orient Programming Features. API’s that automatically support Trace/Debug/Logging are good.

This summer my project was to teach my son to program, (as it was last summer).  We created a SMS text message translator, (eg. CU L8R=see you later), a version of Hammurabi, a primitive predator-prey population simulator, and got started on an MMO as a way to explore object oriented programming.  This year, we wrote our programs from scratch, as opposed to–mostly–copying them from a book.  Last year, we translated code from an old VB for kids book into C#

Whilst writing these programs with my son, I realized I didn’t have quite the API’s I wish I had.

I wish there were some API’s that were domain specific, like Hammurabi-type-game specific.  Most of the games were easy, but had one or two damn hard parts. For example, creating a Dice class that works in ASP.NET turned out to be a major distraction from the more relevant task of understanding the difference between fields, methods, if blocks, for blocks, as so on.

If there was such a pedagogical API, it would have a bunch of functions suitable that would have desirable quantities (going up, peaking, going back down), without a multi-hour detour into how 2nd degree polynomials work. 

Anyhow, if I ever get the time I re-write these mini-applications, factor them into the hard parts and the easy parts and publish them as pedagogical API’s.

I can tell you as a geek who learned programming as a child, I’d rather have had API’s in C#, than a funky kid specific language.  Even as a ten year old I knew that logo was for sissies and real code was in Atari Basic.

In the good ole days of COM, I didn’t have the platform or the audience to let anyone know that COM was a technology only a mother could love. So unusable and arcane–it was elitist.

Now when I blog, I’ve gotten response from project managers at Microsoft. Jeffery Snover (a PM for powershell) replied to one of my posts with my notes about batch versus .net code versus powershell. And now, after getting thoroughly ticked off after a few days worth of work and couple of dollars trying to implement Infocard/Cardspace, I got a response from Kim Cameron, the PM for Infocard–(detailed, even!)