Last night as I was talking with Danny Diaz about the importants of good programming language documentation.  It occurred to me that the level of effort a company puts into its documentation is a direct reflection on how it sees the developer in relation to its products.  If there is a lot of thought, love, and detail put into the documentation the company most likely cares very much about the developers experience from cradle to grave.  If the documentation is haphazardly put together and no common UIX efforts were made then the company most likely cares very little about new developers, and only begrudgingly puts documentation online for its seasoned developers because it is the industry norm and is expected of them.

As a test I decided to look at the documentation posted online for five of the most common languages found out there today, that are tied to a specific company. 

• C# – Microsoft
• Java – Oracle
• Objective-C – Apple
• Ruby (Ruby On Rails) – 37signals (I know this is a framework, but this seems like the company with the most influence)
• PHP – The PHP Group

I needed to compare documentation on a somewhat equal footing, something that was going to be common across all the languages, so I settled on looking at the documentation for strings.  As I was doing this I found some very interesting dichotomies between the layouts and presentation used by each of the companies, some just didn’t care, others cared a great deal.  But the biggest factor was the usability of the documentation, some it looked like they simple wanted to present the information on the screen so they could say they have documentation, others cared very much about the UX, some look like they cared by like anything else a bad design seems to be weighing down their efforts.

Here are the five criteria I used to judge each set of documentations on a 0 to 5 scale.

1. Quality of documentation
   Does the documentation contain just the bare-essentials or does it contain helpful security, performance, and warning considerations that the developers should know about so they don’t run into too many gotcha’s too far down the line.
2. Ease of navigation
   This is important because if you cannot navigate the documentation easily and drill into exactly what you need to look up, it severely hoppers you productivity as a developer.
3. Code use examples
   Sometimes even if you have the API, the use of it isn’t exactly understood from the documentation alone, so examples of how the method should be used are always a welcomed addition for determining if you are on the right track or not.
4. Easy to read URL
   Having an easy to read URL is important, because not only does it help with things like SEO, since Google is always the first place I go when searching for documentation, it also helps in quick navigation of the documentation if you know exactly the class you are looking for.
5. Ease of switching between documentation versions
   Sometimes you queries in Google don’t exactly bring you to the right version of the documentation that you need, but if the site makes it easy to switch between versions then the right documentation is only a click away. Or on the other side of that coin, you cannot be using the latest and greatest in your job, but you still need to find relevant information to the version you are working with.

So lets get started.

PHP

The PHP documentation for strings was very poor, but I think that is because strings are considered to be a primitive in the PHP world, so all they could do was document other methods that interact with strings.  However, their over all documentation was poor and would have only received one out of five if it wasn’t for the excellent user contributed content and examples that each page has.  I don’t know if the excellent user contributed content was born out of necessity of bad documentation, part of the culture, or a combination of both but it seems to get the job done for the most part.  Besides the content the navigation was horrid, there is not an easy way besides search to find other relating documentation, besides drilling back up the navigation tree, and as far as I could see there wasn’t an easy way to switch to the different versions of PHP if you weren’t using the latest and greatest version.  And they seem to maintain this mid-90’s book paging documentation practice that allows you to continue to the next section of the documentation as if it was divided in to chapters, which really only reinforces the point that they haven’t looked at their UX for probably at least 10 years.  So that all contributed to the following scores:

• Documentation Quality (2/5)
• Navigation (1/5)
• Code Examples (3/5)
• Easy Url (4/5)
• Version Switching (0/5)
• Overall (2/5)

Ruby

Note: The documentation provided on Ruby On Rails seems to be a direct copy from Ruby Doc.

The documentation quality was very good, but on the same token very minimal it only gave you very terse information about each method, but the saving grace was definitely the code examples as far as the actual documentation went.  The navigation is very good for in-document jumping around, however it is very poor for browsing other classes in the Ruby language, on the other hand the URL’s seems to be cleanly represented and a power-user would be able to jump between documentation with easy by just using the URL.  Version switching was non-existent.  Which all resulted in the following scores.

Java

The documentation quality was very good, however after you get past the header of the document each method is only tersely documented and there were very few code examples or warning to base your decisions on. The UX as you might be able to tell hasn’t been updated probably since Java was released in 1995, their idea of navigation seems to be based on browser frames and one off targeted screens that just show a list of classes for instance in the namespace.  On the other hand the layout was simple, and a power-user could easily jump around the documentation with a few targeted clicks to find out more about the properties vs methods vs constructor.  The URL is very easy for a power-user to navigate through, because the classes and namespaces are right in the URL including the version, so it is everything you need to get right to the documentation you are looking for.  You can easily navigate to other version of the documentation by just changing the version in the URL, which isn’t ideal, but it is better than no method at all.  The only caveat is that the Java versioning isn’t consistent, but they seem to have redirects in place for common mistakes.  This all resulted in the following scores for the documentation:

Objective-C

The documentation quality is very good, and if I had to guess Apple took the structure of the Java documentation and just added the typical Apple flare to it.  Because most of the elements are laid out in the exact same order as the Java documentation right down to the navigation.  But a plus for Apple is that they got rid of the 90ish navigation techniques and added something a little more modern, but still not that great.  Instead of navigating the document by clicking links you select a drop down which will take you to the part of the documentation you are looking for.  In addition to that they have a nice menu on the right hand side that lets you jump around the class, but nothing more, so you can’t use it to browse the entire library.  One weird thing I encountered which I am still scratching my head at for the reasoning is the next button at the top of the page. It seems to take you just to the deprecated methods and then if you click it again takes you to the document update history, seems totally useless to me.  In addition there was no way to switch between versions and the URL structure was the most horrid I have seen, so that all resulted in the following scores:

C#

Lightweight

Classic

ScriptFree

I have to say that Microsoft is basically the cream of the crop as far as documentation goes.  They have 3 different views of the documentation depending on your needs and habits for browsing.  All 3 of the themes had a very clear UX that really shows that they care about how the developer perceives the documentation.  Because of the three themes the navigation varied slightly between them but all of them were very consistent in layout and approach, which made transitioning easy.  The URL is one of the easiest I have seen, because the structure is /{language}/library/{namespace}.aspx, which is very clear, easy to navigate, and short enough were you can easily tell where you are going before you click a link.  The code examples were top notch and most methods and properties had full code examples that you could copy and past and run right in Visual Studio.  In addition, they allowed community posting on the documentation like we found with PHP.  And Microsoft was the only company that offered switching of versions right in the documentation, even though it was only the Classic theme it was a very nice addition.  For the other themes you can switch versions with the URL.  Other welcome additions was the namespace navigation in the Classic theme and ability to drill out of the namespaces with the other themes and see all the peer classes in each namespace.  Overall I am very impressed by MSDN, which shows in the scores below:

Conclusion

As most of you know that have read my blog for any amount of time, I am a fan of C# as a programming language, and I always knew that MSDN had the best developer documentation.  But it wasn’t until going through this exercise that I realized how far ahead Microsoft is in having one of the best developer experiences around.

I am interested in hearing what you like and hate about each of these documentation sites, and any others you think warrant a mention.

This is a continuation of my Introduction to ASP.NET MVC series. As I outlined before this is in an effort to write the book and keep blogging, I decided to write/blog the last chapter, Chapter 2. I am doing this so I can receive feedback on this chapter as early as possible. Because this chapter, in my opinion, is probably the most critical of the book, it defines the context around ASP.NET MVC and how it differs from ASP.NET Web Forms, as well as giving a historical perspective of the MVC pattern.

In the next several posts we will cover the following parts of Chapter 2 from the book:

• The Model-View-Controller Pattern
• ASP.NET MVC vs. ASP.NET Web Forms
• Installing the Prerequisites
• Your First ASP.NET MVC Project
• The Model
• The View
• The Controller

ASP.NET MVC 1.0 Website Programming: Problem – Design – Solution by Nick Berardi New: $31.49 This item has not yet been released. You may order it now and we will ship it to you when it arrives.

The Controller

In ASP.NET MVC, the controller contains the application logic for manipulating the model, handling user interactions, and choosing the view to display to the browser.  It can be thought of as the glue that holds the model and views together.

The controller, in actuality, is just a class object that inherits from the System.Web.Mvc.IController interface.  However, the typical implementation that you will encounter will be abstracted away from the IController interface, using an already implemented Controller class.  A properly implemented controller will contain one or more action methods, which we will cover in a later section of this chapter.

URL Routes

Another important part of the controller is the routes that define the URL.  The routes tell the controller factory which controller to instantiate and which action in the controller should be executed.  Let’s take the default route, which we learned about earlier in the chapter, as an example:

routes.MapRoute(
    "Default",
    "{controller}/{action}/{id}",
    new { controller = "Home", action = "Index", id = "" }
);

In the above route definition, the URL can be constructed in the following manner:

{controller}/{action}/{id}

How the controller and routes work is one of those instances where it is easier to demonstrate the capabilities than to try to explain, so here is a table to demonstrate how the above route breaks up the following URL’s.

You may have noticed in the above table that some of the parts of the URL are not defined, and in the first case none of the parts are defined.  This is because there are a set of defaults defined for each part of the URL, and if the part of the URL is missing, then the default is used.  The default is defined with the following line in the above example code:

new { controller = "Home", action = "Index", id = "" }

In ASP.NET MVC there are two parts that need to be present in every route and they are controller and action.  This is because these two parts are required by the controller factory to find the correct controller object and then the correct action method in that controller.  All the other parts can optionally map to the action methods parameters.

When we talk about the controller factory from here on forward, we will be specifically referring to the ASP.NET MVC implementation, called DefaultControllerFactory, which is based on the controller objects using the following format: {controller_name}Controller (i.e. HomeController, AccountController).  There are many other types of controller factories, such as those based on the Inversion of Control principle, Castle Windsor, Sprint.NET, Structure Map, and Unity that are available from the MVC Contrib project located at www.codeplex.com/mvccontrib, if you are interested in learning more.

Controller Factory

The default controller factory in the ASP.NET MVC Framework, the DefaultControllerFactory, uses the following criteria, by default, when searching for available controllers for use:

• The namespace of the web assembly with Controllers added on the end (that is, TheBeerHouse.Web.Controllers).
• The objects in the namespace must be in the following format {controller_name}Controller (that is,  HomeController, AccountController).
• The objects must also inherit from the IController interface.

These criteria can best be seen in the default solution that we saw earlier in this chapter. Let’s take another look at the controllers, as seen in Figure 2-25.

Figure 2-25

All of those criteria may have made the process of adding a new controller sound complex, but really all that you need to do to accomplish this is add a new code file to the Controllers directory and make sure the object in the code file inherits the Controller object from the System.Web.Mvc namespace.

Actions

The actions, like we talked about earlier in this chapter, are what binds the URL to the view being displayed.  They are not that difficult to understand, but to help separate out the different parts that make up an action I have divided them into a couple of logical sections below.  We are going to use the following code example to help bring all of the different sections together.

[AcceptVerbs(HttpVerbs.Post)]
[OutputCache(Duration = 600)]
public ActionResult GetCustomer (string name, string email)
{
    // code for executing the GetCustomer action
    return View(customer);
}

Methods

When we refer to an action, we are actually talking about a standard .NET method with parameters, return values, and attributes just like any other in your code.  The only thing that makes it an action is the fact that the method is inside of a controller class.

In the above example code the whole thing can be considered our method, and is probably pretty similar to every other method that you have ever seen or developed.

Results

A result is just another name for the return value of the method.  The only criterion for the return value is that it must be, or inherit from, the type ActionResult.

In the example code above, the result type is ActionResult, but it actually returns an object that inherits from ActionResult called ViewResult.  The ViewResult is created from a protected method available on the controller called View() which does all the necessary instantiating of the ViewResult to be returned.

Filters

The filters are implemented as attributes on the action methods.  There are two types of filters, one for actions and another for results.  The action filter refers to the action method and has two events. One is for custom processing before the action method has been executed and the other is for after the action method has been executed.  The results filter refers to the HTTP response and has the same two events that the action has, one for before the response is sent and one for after the response is sent to the browser.  We are not going to go into great detail about filters in this book, however we will be using them for such things as authorization, caching, and RESTful service results.

In the sample code above, the filter is the attribute called OutputCache.

Selectors

The selectors are implemented as attributes on the action methods.  Since both filters and selectors are implemented using attributes it is often difficult to determine the difference between them, but there is a huge difference.  The selectors are used when the controller factory is trying to determine which action method is the correct one to process the request, so they really have nothing to do with the action method execution, just the selection of the action method by the controller factory.

In the sample code above, the selector is the attribute called AcceptVerbs.

This post is licensed under a different license than the rest of my site. Copyright © Wiley Publishing Inc 2009

This is a continuation of my Introduction to ASP.NET MVC series. As I outlined before this is in an effort to write the book and keep blogging, I decided to write/blog the last chapter, Chapter 2. I am doing this so I can receive feedback on this chapter as early as possible. Because this chapter, in my opinion, is probably the most critical of the book, it defines the context around ASP.NET MVC and how it differs from ASP.NET Web Forms, as well as giving a historical perspective of the MVC pattern.

In the next several posts we will cover the following parts of Chapter 2 from the book:

• The Model-View-Controller Pattern
• ASP.NET MVC vs. ASP.NET Web Forms
• Installing the Prerequisites
• Your First ASP.NET MVC Project
• The Model
• The View
• The Controller

ASP.NET MVC 1.0 Website Programming: Problem – Design – Solution by Nick Berardi New: $31.49 This item has not yet been released. You may order it now and we will ship it to you when it arrives.

The View

In ASP.NET MVC, the view is the presentation of your applications’ business layer or model.  Typically with ASP.NET MVC this is HTML, but your view can be rendered in any form that can be transmitted over the internet, including JSON, XML, binary, RSS, ATOM, and your own customized protocol if you have one.

These dynamic ranges of views that, allow it to be capable of such a wide range of delivery types in the ASP.NET MVC Framework are because of a provider engine appropriately called the view engine.  The view engine is responsible for taking the controller and action names and then delivering the right view based on these names.

When I talk about the view engine from here on forward, I will be specifically referring to the ASP.NET MVC implementation, called WebFormViewEngine, which is based on the aspx, ascx, and master files.  There are many other types of view engines, such as Brail, NHaml, NVelocity, and XSLT that are available from the MVC Contrib project located at www.codeplex.com/mvccontrib, if you are interested in learning more.

ViewEngine

The default ViewEngine in the ASP.NET MVC Framework, the WebFormViewEngine, uses a hierarchy of folders and aspx and ascx files when rendering HTML pages to the browser.  The WebFormViewEngine, uses the standard ASP.NET Web Forms rendering engine that has been present in the framework since version 1.0, however the emphasis has been moved from control based rendering to an inline code based rendering that is reminiscent of its predecessor, plain old ASP.

Let’s take another look at the hierarchy that the default view engine uses, as seen in Figure 2-24.

Figure 2-24

The view engine treats aspx and ascx files almost equally, so that it is possible to render your HTML from an ascx or user control file, in the same way that an aspx or page file works.  As you can probably imagine there needs to be a hierarchy or order to which an aspx or ascx file is picked from the controller or Shared directory in Figure 2-24.  The default ASP.NET MVC view engine uses the following lookup order, from top to bottom, when trying to determine which view to render.

1. ~/Views/{controller}/{action}.aspx
2. ~/Views/{controller}/{action}.ascx
3. ~/Views/Shared/{action}.aspx
4. ~/Views/Shared/{action}.ascx

What this above lookup order means is that:

• Controller directories are always checked before the Shared directory.
• aspx or page files are always checked before the ascx or user control files.

The above lookup order even applies to master files, which allows you to select the master page template that you want to render with your view.  The lookup order that the master pages follows is slightly different than the page and user controls:

1. ~/Views/{controller}/{master_name}.master
2. ~/Views/Shared/{master_name}.master

Now that we have learned how view pages, controls, and master page are selected let’s take a little closer look at the files themselves.

ViewMasterPage, ViewPage, and ViewUserControl

In ASP.NET MVC there are three new takes on objects that you are probably familiar with from ASP.NET Web Forms.  These types probably come as no surprise, given what we just covered in the ViewEngine section and the title of this section, but they are as follows listed with their Web Form equivalent.

These object types in MVC are actually inherited from their Web Form counterparts, because they rely on their built in execution, in the ASP.NET Core, as a way of delivering the content through the servers such as IIS.  So all the interfaces you have become acustumed to (i.e. User, Context, Request, Response, IsPostBack, etc.) are still available in the MVC version of the page, user control, and master page.

However when developing for MVC there is a primary difference in the way in which an MVC view is constructed in the code-behind compared to its Web Form counterpart.  The best way to illustrate this difference is by showing you all that this required to have a fully functional view in MVC:

public partial class MyViewPage : ViewPage
{
}

Yup, that is all that is required, pretty cool huh?  This is possible because all the application logic that used to be in button clicks, post backs, and other event actions, has been moved to the controller actions.

It is actually considered bad practice in ASP.NET MVC to put any code in the code-behind file.

We have covered the basics of how views are rendered and found and the differences between MVC views compared to their Web Form counterparts.  We will be going in to a great depth of detail on programming views in later chapters of this book.  However we are not quite done, there are a couple more basics things I want to cover before moving on to The Controller section.  These include special properties designed to allow easy communication between the model, controller and view.

I have broken up the properties in to logical sections, so that we can discuss the purpose and intended use of each of them as envisioned by the ASP.NET MVC team.

ViewData, and Model

The ViewData property is used to store and transmit data from the model and controller to the view for rendering.  It can either be used as a Dictionary object, such as:

<%= ViewData["text"] %>

Or as a typed model object, such as:

<%= ViewData.Model.CustomerID %>

That is defined using generics in the inheriting object, such as a Customer type in the ViewPage:

public partial class EditCustomer : ViewPage<Customer>

It is a very versatile collection that is available to both the views and the controllers, and is passed via the ViewContext, which inherits from the ControllerContext.

TempData

The TempData property is a session-backed temporary storage dictionary, much like ViewData, which is available for the current request, plus one.  What this means is that any data you store in the TempData is kept in the session storage for one additional request, beyond the one you’re currently processing.

You may be scratching your head like I was when I first learned about TempData, and wondering why this would be important enough to include in the framework.  There is actually a very simple answer to this question, it allows you to pass data across requests, much like you have been accustomed to with the ViewState that is used in Web Forms.  It is also great for passing data between redirects, say you have the following scenario:

A user comes in to your site unauthenticated and you have to redirect them to the login page, but you what to display a message saying they need to login before viewing the content, but that message should display only when they don’t visit the login page directly.

Previously to accomplish this type of process you had to jump through hoops to determine if the user came from another page on your site, by checking the referrer or some other custom process that you had to come up with.  Additionally even after you got this done it was hard to customize that message to give the user some indication of where they came from or are going after they login.  TempData really comes to the rescue in this case, because you can the following is the only code that you need to display that message:

<% if (TempData["Message"] != null) { %>
<div class="message"><%= TempData["Message"] %></div>
<% } %>

You can even put this code in your master page so that you can display a message to your user on any page in your site, and all that you need is these three lines of code in the view.

HTML and AJAX Extension Methods

The HTML and AJAX extension methods provide a way to generate snippets of code for such things as form inputs and links.  For example if you wanted to generate a text box with the name attribute set to CustomerName, you just need to put the following in your view:

<%= Html.TextBox("CustomerName") %>

And it will generate the following HTML:

<input type="text" name="CustomerName" id="CustomerName" value="" />

As one added feature if you actually wanted to render the page with CustomerName already filled in, you would just need to set ViewData["CustomerName"], in the controller, equal to whatever you want to be rendered in the HTML.

An extension method for all of the form inputs available through HTML, have been provided with the ASP.NET MVC Framework, plus some other extensions such as AJAX implementations of the form inputs, and anchor link generation for controller actions.  Ninety-nine percent of all the HTML and AJAX extension methods that you will need to generate a web page have been provided in the framework, and if there is something that you must have, you can extend your own method from the HTML helper by doing the following:

public static string MyCustomControl (this HtmlHelper html, string name)

The this keyword is what is used to add these custom methods on to the HtmlHelper, which is represented as Html in the view pages, we will cover extension methods in greater detail later on in Chapter 6.

This post is licensed under a different license than the rest of my site. Copyright © Wiley Publishing Inc 2009