As is probably apparent if you’ve read any of my blog posts. I’ve been fascinated with personal computers for a large part of my life. I’ve had an obsession with them and their power to change my life…

Starting with this:

This is a story of how the Apple IIe changed my life.

One of my best friends, Zach, and I used to out-nerd each other in the computer lab of our grade school. Zach’s parents were newspaper folks. So they (and naturally, Zach) lived, breathed, and loved their Macs. I was solidly on the I-B-M side of the line.

The computer lab consisted of about 25 Apple IIe machines, a Mac Powerbook, and an IBM PC. Zach and I were the only two kids that were big enough dorks to be allowed to touch the PowerBook or the PC – which sucked in middle school, but has paid off handsomely in our “old age.”

So, that was the state of things in 1992, I continued on my path being a PC sympathizer, and Zach stayed in the Mac camp. We had mutual respect for one another. Zach has even used a PC when he had to (although, I cannot say I was so open-minded).

Andrew & Zach, ca. 2000

There were times when we disagreed on things, and I was not always the best friend in the high school years. Looking back, there are any number of paths our lives could have taken. I could have been sick the day that Zach showed up in 4th grade. Zach could have decided that my disdain for Macs was too much to bear. But as it turns out, we’ve been friends for almost 20 years, and outside of my wife, there is no one else on this planet that I trust as much as Zach. I sometimes wonder what other directions our lives might have gone, but I am mostly thankful for the way they’ve turned out so far.

Happy Birthday Zach.

P.S. Zach did eventually win the little Mac battle, but that’s another blog post.

But I don’t want to rehash that.

Today, I want to talk about when and why to comment.

When I create a new class definition, I typically try to add a summary comment right then. I also expect this of my team members. It may seem pedantic, but there’s a very good reason for it.

Expressing in English* the intent of the class tends to help me clarify the Single Responsibility that I have for that class. If I find that I have trouble specifying the expected behavior of a class in the summary, that generally means I don’t have the plan for why/how/when I need to use that class.

If I find I need a paragraph to explain the purpose of the class, it might be doing too much.

Doing too much is bad.

So, when I find that this is the case, I look to see which parts of the summary should be broken out — those breakouts typically fall along class definition lines, and before I know it, I can summarize most classes in one or two sentences, and the only do as much as they should.

Only doing as much as you should is “A Good Thing.”

The other benefit is that my colleagues can take a look at my code and understand large blocks without digging though and inspecting each member of the class. Truly, that was the point of OOP. Rather than trying to explain how each block of code works (inline comments), explain why each block of code exists (first-class documentation).

This rule of thumb works the same for members of a class. If you can type out a sentence explaining what you’re trying to do, there’s a much better chance that you will actually do that thing. There’s even a good chance that you’ll be able to identify things that are leaking in and shouldn’t be.

If When your code has gotchas, these should be outlined in the block, or the blocks. This is your chance to explain yourself. Do you need that string to be formatted just so? Do you return something in a particular order? What do you expect from consumers?

While I’m on this subject, please don’t just fill out comments to make the compiler warnings go away. That’s just a waste of your time.. I am aware of a particular tool that provides phantom summaries; summaries that are there, but have no substance. The intentions were good, but it entirely misses the point.

Imagine you bought a dictionary and all of the definitions used the word in the definition.

Definition: A sentence that defines something.

C# and Java both have great documentation support, I believe that other languages/platforms have started to make these summary-type comment sections closer to “first-class citizens,” so your reasons for not commenting code is dwindling.

I’ll leave you with this: Every line of code makes perfect sense while you’re writing it. Really good code will make sense to other people with a little bit of explanation. Great code is that which can be understood by your future self, and the people that follow you. Why not hedge your bets and provide some good documentation to make your good code, great code.

* It doesn’t have to be English, the first language of your team is best for these comments.

When it comes to code, I’m pretty particular about how things are named. To me, naming both classes and class members is one of the fine arts of software development. I actually think that this can demonstrate quite a bit about someone’s experience, what they understand about the software development life cycle, and ultimately, they conceptual understanding of Object-oriented design. That’s why this particular “code smell” bothers me so much.

I’ll call it the “Named Generic” pattern.

we’ve all seen it. A developer wanted to specify a typed parameter, but missed the boat.

For example:

public RecallList GetRecalls(AutoMakersList automakers)
{
// do something useful with each automaker and yield the recalls associated with them.
}

So far, this code isn’t bad. We have a decent method name, the parameter name is ok, but what are the two type definitions here:

public class AutoMakersList : List{ /*no body*/ }
public class RecallList : List{ /*no body*/ }

Uh oh.

With two classes I have simultaneously reduced flexibility, and increased complexity. From the perspective of the consumer of this method, I now have to marshal a set of strings, then add them to a new class called AutoMakersList, which I had to search out and attempt to understand.

From the API designer’s perspective, I’ve placed some requirement on what is legal to pass in. Except I haven’t. The list is still of string, and the last time I checked, there were no validation methods on string that validate they are auto maker’s names (C# 5.0, maybe?). So I’ve really just obfuscated what I wanted to happen, which was this:

“hand me an enumerable of validated automakers”

The same could be done with this method signature:

///<summary>This will produce the recalls associated with the specified automakers.</summary>
///<param name="automakers">This is a pre-validated set of automakers for which recalls
/// will be retrieved. Valid automakers follow these rules: .....
///</param>
public RecallList GetRecalls(IEnumerable automakers)
{
//iterate over each automaker, and do something interesting to yield out their recalls
}

In Visual Studio (and perhaps MonoDevelop?), I’ve now told the API consumer what I expect, they will get it intellisense when they’re constructing the call. Whereas, if I just told you to hand me an AutoMakersList, there’s ambiguity in what is required. A side note is that Code Contracts are very helpful, and you should consider using them anyway, but that’s not the point of this post. The other benefit of this approach is that I’ve reduced the calling requirements on this method. The above example is actually not done yet, and here’s where it will *seem* like I’m contradicting my point, but I’m not, really.. really.

public RecallList GetRecalls(IEnumerable automakers)
{
//do something interesting.
}

public class Automaker
{
public String Name{get; set;}
public bool IsValid(){return valid;}
}

Instead of passing in just a a list of string, why not pass in “Automaker?” On the surface, it seems very much like just passing a simple String, the difference is that I have attached the context explicitly to the Name property, instead of implicitly from the name of the collection in which the object was stored. Let that marinate in your brain for a minute. They’re actually radically different concepts, one of them works, and IMHO, one of them doesn’t.

Part two…

“RecallList”

Here, the API designer got it half right. The the context for each recall is explicitly attached to the object that cares — “Recall”, but RecallList doesn’t actually add any value, it essentially says “this is a list of Recall”, which is the same thing as what “List” says, in a much more concise way. Although I think Classes are *cheap* *cheap* *cheap* and people are too often reluctant to add them, in this case “RecallList” is just *redundant* *redundant*.

Finally, passing a list in or out adds extra overhead that neither the API designer or the caller needs. In both cases, List places extra requirements on either side of the call, when really everyone meant to say, “here’s a set of something that you can read through. (IEnumerable)” When we apply all of these suggestions together, this is the method we’re left with:

///<summary>This will produce the recalls associated with the specified automakers.</summary>
///<param name="automakers">This is a set of automakers for which recalls will be retrieved.</param>
public IEnumerable GetRecalls(IEnumerable automakers)
{

// iterate over each automaker, use the "IsValid()" method to determine if it should be processed,
// and do something interesting to yield out the recalls
}

As I said at the beginning of the post, if you’re familiar with SOLID, most of this post will make good sense to you, but I wanted to try to put it in a context of code you’ve probably seen. Let me know what you think in the comments.

NoRM is a .net library to interact with the document-oriented database MongoDB. We set about doing this in a way that makes sense for the C# developer who doesn’t want to spend an inordinate amount of time configuring the database. As you’ll see in a moment, with NoRM, there’s very little you need to do to get started with MongoDB.

NoRM stands for “No Object-Relational Mapping” – it seems that people are concerned about leaving relational databases because they’ll lose the low-friction environments they’ve come to expect (think ‘LINQ-to-SQL’). Another concern around moving to a NoSQL option is the notion that these datastores carry little or no structure. By creating a strongly-typed interface to MongoDB, I feel that we have addressed both of these concerns.

So, just to whet your appetite, here’s an example of how you’d use NoRM to store some widgets.

//First, define your document (this can be very similar to your concept of "Model" -- notice there's no special attributes or configuration.)
public class Widget
{
public ObjectId Id {get;set;}
public String Color {get;set;}
public double Price {get;set;}
public DateTime ReleaseDate {get;set;}
public IEnumerable Reviews {get;set;}
}
//Next, spool up a connection to your database 
//(The DB doesn't have to exist yet, but MongoDB DOES need to be running)
using(var db = Mongo.Create("mongo://localhost/ProductDB")
{

//Get a reference to the collection in which we want to 
//store our Widgets (doesn't have to exist yet.)
var widgets = db.GetCollection();

//create a widget instance.
var topSellingWidget = new Widget{ Id = ObjectId.NewObjectId(), Color = "Red", Price = 39.95,
ReleaseDate = DateTime.Now, Reviews = Enumerable.Empty() };

//now, save the instance
widgets.Save(topSellingWidget);

//lastly, retrieve it from the DB.
var hydratedTopSellingWidgetFromDB = widgets.FindOne(new {Color = "Red",Price = 39.95});
}

That’s just a taste of the simplicity that is NoRM, there’s a huge amount of functionality that I’m not covering including:

• Fluent configuration
• Solid LINQ support
• Advanced update capabilities (update single or multiple documents that match template documents)
• Map/Reduce functionality.
• Support for MongoDB operators via the “Q” (Qualifiers) and “M” (Modifiers) classes.
• If you need it, “Weakly-typed” interaction via the “Expando” class.
• Bulk-insert capability (a la SqlBulkCopy)

Aside from actual “features”, there are lots of elements that make software good, here’s a few things I think make NoRM awesome:

• Tests: We have more than 400 tests that verify the functionality found in NoRM, and although we have just reached the v0.9.0 milestone, the library is very stable, and I am aware of production deployments using NoRM, today.
• Participation: I started NoRM in the last few days of January 2010, and have seen incredible participation from the Open Source community – I’ve learned a lot about what people do — and don’t — need in a library, and some of the interesting pieces of helping to shape an Open Source project (hopefully I can share that in another blog post). We have a vibrant community at http://groups.google.com/group/norm-mongodb.
• Pragmatism and Experience: I am routinely impressed by the ideas and code that the project’s contributors bring forward.

Please download and use the library:

• Stable Milestone: http://github.com/atheken/NoRM/zipball/v0.9.0,
• Project Page (the master branch will always “Stable”): http://github.com/atheken/norm.

Remember that we want NoRM to be the best C# driver for MongoDB possible, so please give us feedback, either in the Google Group or follow me on twitter (@atheken).

Cheers.

If you’ve been following the latest trends in the .net world via reddit, twitter, or your favorite blogs, you’ve been seeing a great deal of chatter about a term called NoSQL. Some might even call it a ‘movement’ but that scares me just a little bit – when things become ‘movements’, their meanings become a bit nebulous. Here are a few cases where a ‘NoSQL’ solution might be useful to you:

• You have a several multi-million row tables that each have foreign key relationships to one another, joins against these tables pound the server, but must return rapidly.
• You have “jagged” datasets where each record has a different composition of fields and children, those children in turn have their own properties.
• You need to find a root record based on a complex set of relations to other tables.

A New Hope:

There are many NoSQL options out there right now, but for reasons that will become obvious very shortly, I am going to talk about one in particular: MongoDB. MongoDB is a “document-oriented” database written in c++ that stores your documents in a format called “BSON.” BSON is conceptually similar to JSON, but is a binary format that also explicitly carries type information.

Mongo has some nice features, including:

• Dynamic creation and allocation of databases and document collections (including the capability of having nested collections)
• Ability to do deep-graph searches (i.e. locate documents based on child properties of the document)
• Ability to execute arbitrary JavaScript functions for aggregation and as criteria of searching
• Very few requirements on what can be inserted into a database
• Support for regex searching.
• Speed
• …more…

But you should be warned: MongoDB doesn’t make ACID guarantees. If you’re storing twitter updates, you’re probably ok, if you’re storing financial transactions, don’t use MongoDB.

But this is a blog about C# where we have strong & static typing, we live and breath order in our daily lives (ha!). “Leave all that ‘No SQL’ to those dirty Ruby hippies”, you say.

Let me break it to you: NoSQL doesn’t mean NoStructure.

To that end, I’ve been (with lots of help) incubating a project on GitHub called NoRM. In brief, NoRM is a library to connect to MongoDB using .Net (and Mono) and to query and hydrate documents into strongly & statically-typed documents in a way that doesn’t make us C# developers queasy.

We still have a long way to go before a 1.0 release, but I think it’s important to point out some of the guys that have been most enthusiastic about this project (and contributed some great code and ideas) include:

James Avery
Jason Alexander
Rob Conery
Nate Kohari
Karl Seguin

These guys really know their stuff, and I am so happy to have them working on this with me. My next post will be about some of the design decisions we’ve made with NoRM and how you might use it (soon) in some of your own projects.

public static class Utilities {        
   public static void Each<T>(this IEnumerable<T> enumerable, Action<T> lambda)        
   {
    foreach (T item in enumerable)
    {
     lambda.DynamicInvoke(item);
    }
   }
  }

With the above, I can convert a block like this:

foreach(var i in enumerableOfObjects)
{
  i.doSomethingInteresting();
}

into something like this:

   enumerableOfObjects.Each(i=>i.doSomethingInteresting());

If you’re using iteration frequently, this can be very helpful shorthand. Remember, you can also do multiline lambdas like the following.

enumerableOfObjects.Each(i=>{ i.doSomethingInteresting(); i.doSomethingElseInteresting(); });

I think one of the greatest risks for Wave is that the idea may be so far ahead of its time that people won’t “get it.” There are a great number of people out there that are invested in private communications and the very idea of someone else editing their content (even if the audit history is there) will make them very uncomfortable.

When you think of Google’s position, it’s clear that they are so far ahead of the curve that they can take risks and put stuff like this out there – which allows them to change the rules and get buy-in.

I think most interestingly, Google is going to make this an open protocol – which is really the only way it can be successful. Think ‘http’, ‘ftp’, ‘smtp’ all these protocols needed to be widely available for implementation or they would have failed. ‘

While we have incredible challenges in our time, looking at things like Google Wave that require us to rely and trust each other more (and create new efficient ways to share information), I can’t help but feel positive about what the future holds for us.

• I’m a software developer for a small Software as a Service company in Durham, NC. We have a .Net Web Application. I’m still a software engineer, but 2009 got me, and so I have moved on to a large company that you might have heard of. Still doing .net development fulltime.
• I have a Bachelor of Science from Ohio State, but not in Math, Engineering, or C.S. I completed some coursework in C.S. at Ohio State, and did pretty well, this included Assembly, OOP, and a sequence called RESOLVE/C++.
• I have been using and abusing personal computers since I was 11 years old.
• The vast majority of knowledge that I have about software development has come from work experience, and independent study (although, I credit RESOLVE with introducing me to many critically important C.S. concepts).
• This post was going to be part of an upcoming post, and I already refactored it into this post, this might also tell you something about how I think about software.
• I am passionate about using software to create efficiency, and improving the quality of life for myself and others.

I hope you all had a happy and safe Christmas.

Rock On!

Essentially, so long as you’ve told your client code that you might throw an exception of a certain type, it’s OK to throw it. I more or less agree, but I typically would rather send back a sane result from a method. Maybe a post on that soon.