If you are a software developer and you haven't downloaded the Community Server Software Development Kit (SDK), you are definitely missing out. This baby is chock full of goodies ... and I'm not talking about stuff that is just cool, rather stuff that is both cool and quite useful. Let's not get the two mixed up.
For those not familiar with Community Server, don't let the name confuse you. When you hear or read the word Server don't think in terms of an operating system or web server (i.e. Windows, Linux, IIS, Apache, etc); instead think more along the lines of a common application framework. After you dive into the SDK, you will understand that the name refers more to the shared capabilities than any specific application(s). You will also find that the applications which come pre-integrated are great examples of how to build web applications on top of Community Server to enable Online Community. It's kind of like when you order a computer and you get all that free software ... uh, maybe not. Enough on that topic... you can get your fill at www.CommunityServer.org.
The first time I downloaded the SDK, I was a bit overwhelmed ... in more than one way. I was both amazed at all the stuff included and confused at how to effectively navigate through it. For this reason, I have decided to revisit my first experience and share some recommended changes in an effort to help reduce confusion for future developers.
This post focuses primarily on file structure and namespaces. The SDK contains a lot of folders and a lot of namespaces. The table below attempts to illustrate the folder in which a given namespace is implemented. For the most part, each top-level folder in the SDK contains a Visual Studio project and associated class files to create an assembly or class library. The Web folder is an exception as it contains the code to pull all the assemblies together and create a single Web Application. The left column of the table, Folder, shows the name of a top-level folder while the right column, Namespace(s), shows the namespaces contained in the assembly created by classes in that folder.
* NOTE: To improve formatting of this table, I have replaced all instances of CommunityServer with [CS].
| | Folder | | Namespace(s) |
 | Blogs 1 |  | [CS].Blogs.Components, [CS].Blogs.Controls |
| [CS].Spam 1 | | [CS].Spam, [CS].Spam.Rules |
| [CS]Reader 1 | | [CS].Reader.Components, [CS].Reader.Controls |
| [CS]SearchBarrel | | [CS].Components.SearchBarrel 2 |
| Components | | [CS] 3, [CS].Components, [CS].Components.Enumerations 4, [CS].Components.HttpHandler 4, [CS].Configuration 5 |
| Controls | | [CS].Controls, [CS].Controls.Utility |
| Data Providers /SqlDataProvider 6 | | [CS].Data 7, [CS].SqlDataProvider 7 |
| FileGalleries | | [CS].Files, [CS].Files.Components, [CS].Files.Controls, [CS].Files.Providers |
| Forums 1 | | [CS].Components 8, [CS].Discussions.Components, [CS].Discussions.Controls, [CS].Discussions.Controls.BaseClasses, [CS].Discussions.Controls.PostDisplay 9, [CS].Discussions.Controls.Search, [CS].Moderation.WebServices 10 |
| Galleries | | [CS].Galleries, [CS].Galleries.Components, [CS].Galleries.Controls, [CS].Galleries.HttpHandler 11, [CS].Galleries.Providers |
| RollerBlogs | | [CS].RollerBlogs.Components, [CS].RollerBlogs.Controls, [CS].RollerBlogs.Data |
| Web | | [CS], [CS].ControlPanel 12, [CS]Web.ControlPanel 13 |
You will notice many superscript numbers in the table. Each of these corresponds to a recommendation for improving SDK usability. I am attempting to stay away from any architectural or naming preferences in an effort to focus solely on improving a developer's SDK experience.
- Folder Naming: I don't think most developers care that the folder name reveals the exact namespace of the assembly it creates, but it would make life easier if the names were consistent. There are two options here: one, change all the folder names to be the same as the top level namespace, or two, change all the folder names to be the top level namespace minus CommunityServer (we can probably assume that part). Although I prefer to have the full namespace as the folder name for clarity, most of the folders use the second option. Recommended change #1: consistently rename the top level folders.
s - You may also notice that several namespaces seem out of place. For example, the CommunityServerSearchBarrel folder contains a project which creates an assembly for CommunityServer.Components.SearchBarrel. There is probably a good reason this was chosen... but it just seems out of place. Perhaps this is because all other sub-namespaces of CommunityServer.Component are in the Component folder? Regardless, recommended change #2 is to either change the namepace from CommunityServer.Components.SearchBarrel to CommunityServer.SearchBarrel or move the CommunityServerSearchBarrel folder into the Components folder and rename it to SearchBarrel.
s - Another example of an out of place namespace is in the Components folder or the CommunityServer.Components assembly. You will notice there are classes in the CommunityServer namespace that are contained in this assembly. If these classes truly belong in the CommunityServer namespace they probably shouldn't be in this folder. If they don't belong in the CommunityServer namepace then they should be moved to that namespace. Considering they are already part of the CommunityServer.Components assembly, I'm guessing it would be safe to keep them there. Thus, recommended change #3 is to move the classes which logically reside in the CommunityServer namepace but physically reside in the Components folder to the CommunityServer.Components namespace.
s - Recommended change #4 is to move items in the CommunityServer.Components.Enumerations and CommunityServer.Components.HttpHandler into the CommunityServer.Components namepace. These namespaces add complexity and are unnecessary.
s - Recommended change #5: Either move classes in the CommunityServer.Configuration namespace into a separate assembly or change the namespace to CommunityServer.Components.Configuration.
s - In relation to the discussion in #1 about folder names, the nested SqlDataProvider folder adds unneeded complexity. Initially, I'm sure it was a great idea for scalability, but not necessary anymore... so get rid of it. Recommended change #6 is to move all files in the SqlDataProvider folder up to the Data folder.
s - The CommunityServer.SqlDataProvider assembly contains two namespaces: CommunityServer.Data and CommunityServer.SqlDataProvider. This is confusing. Most of the classes are contained in the CommunityServer.Data namespace and many of them seem to be specific to a Sql-based data provider implementation. Recommendation #7 is to have CommunityServer.Data and CommunityServer.Data.Sql only. Sql specific classes could be moved to the new Data.Sql namespace.
s - The CommunityServer.Discussions assembly contains one enumeration which is in the CommunityServer.Components namespace. This recommendation, #8, is simple: either move the enumeration to the Components folder or to the CommunityServer.Discussions.Components namespace.
s - CommunityServer.Discussions.Controls.PostDisplay seems more like a class name than a namespace. Is it really necessary? Recommendation #9 is to move classes in this namespace to the CommunityServer.Discussions.Controls namespace (the physical file locations do not necessarily need to change).
s - Recommendation #10: change CommunityServer.Moderation.WebServices to CommunityServer.Discussions.WebServices.
s - Similar to #4 and #9, recommendation #11 is to move classes in the CommunityServer.Galleries.HttpHandler namespace to the CommunityServer.Galleries.Components namespace.
s - The CommunityServer.Web assembly primarily contains classes in the CommunityServer.ControlPanel namespace. For consistency and clarity, recommended change #12 is to change CommunityServer.ControlPanel to CommunityServer.Web.ControlPanel.
s - Perhaps this is a result of a typo? There are four classes implemented in the CommunityServer.Web assembly which use the CommunityServerWeb.ControlPanel namespace. Simple fix. The final recommendation, #13, is to change all classes which use the CommunityServerWeb.ControlPanel namespace to use CommunityServer.Web.ControlPanel.
Now, obviously this is the view from Kyle's world... I'm quite interested to know what you think about SDK usability.
In general, what makes an SDK easy or hard to use?
Specifically, what makes the Community Server SDK easy or hard to use?