<CharlieDigital /> Programming, Politics, and uhh…pineapples

Procedural vs. Structural Code

In working with my development team, one of the things I've been working on is to figure out how to get them to be more object oriented. I've written about this topic before and I continue to evolve my expression of this idea to other developers that I work with.

To me, beyond the simple textbook definition of object oriented programming, at the level of construction, what it really boils down to is expressing logic structurally as opposed to procedurally. That is the very basis of what I've been trying to communicate and trying to understand how to impart that on other developers.

As a basic example, let's consider a user management API that has three operations for add, update, and delete.  Suppose I want to send a sequence of actions to this API.  We see this type of pattern of interaction all the time.  Assume we have a repository class:

public class UserRespitory
{
    public void Add(User user)
    {
        Console.Out.WriteLine("Added!");
    }

    public void Delete(User user)
    {
        Console.Out.WriteLine("Deleted!");
    }

    public void Update(User user)
    {
        Console.Out.WriteLine("Updated!");
    }
}

I've left the implementation of the actions intentionally simple.  Now assume that we have an operation and a user class like so:

public class Operation
{
    private readonly string _type;
    private readonly User _user;

    public Operation(string type, User user)
    {
        _type = type;
        _user = user;
    }

    public string Type
    {
        get { return _type; }
    }

    public User User
    {
        get { return _user; }
    }
}

public class User
{
    private string _username;

    public User(string username)
    {
        _username = username;
    }
}

Consider a use case where we must build an API to support bulk operations.  The typical implementation pattern that I will encounter will look more or less like this:

private static void Main(string[] args)
{
    List<Operation> inputs = new List<Operation>
    {
        new Operation("Add", new User("Charles")),
        new Operation("Update", new User("Steve")),
        new Operation("Delete", new User("John"))
    };

    UserRespitory repository = new UserRespitory();

    foreach (Operation operation in inputs)
    {
        switch (operation.Type)
        {
            case "Add":
                repository.Add(operation.User);
                break;
            case "Update":
                repository.Update(operation.User);
                break;
            case "Delete":
                repository.Delete(operation.User);
                break;
            default:
                throw new InvalidOperationException();
        }
    }
}

This is pretty much textbook procedural code and, as a consultant, this is pretty much the code I expect to see (and have seen countless times) on projects.  Of course, this is a pretty harmless case; in measuring the cyclomatic complexity and maintainability index of this code using Visual Studio's built-in analysis tools, I get values of 7 and 67 for each respectively.

Already a 7 with just a basic implementation.

Cyclomatic complexity is a good tool because it gives us a quantitative metric of code quality that is indifferent to "style" or any qualitative prejudices that individual developers might have -- it's a pretty good starting point for determining where to focus your time in terms of code reviews and refactoring.  With that said, a value of 7 is certainly not bad (the NIST guidelines recommend a limit of 10 for methods), however, I think we've all encountered this before: if-else's nested under switch's nested under if-else's nested under for-loops and so on.  When I see this pattern, I usually encounter it in the 20-30 range (and I've seen it in the 100+ range, sadly (an extract from a 1078 line method with cyclomatic complexity of 136 in production code -- I couldn't zoom out far enough to capture the whole thing)) for cyclomatic complexity simply because the developer doesn't know when to stop the madness.

Well, let me correct that last statement: when a developer starts down this path and once they've gone deep enough, there is simply no way that they can recover from the madness without structurally refactoring the code; the switch-case traps you into a cycle of cancerous code unless you can find a different way of representing the same logic in a more modular, orthogonal manner.  To me, this is really the heart of understanding object oriented programming.  How we achieve this -- in this case -- is quite simple, really.  For starters, we make the operation abstract:

public abstract class Operation
{
    private readonly User _user;

    public Operation(User user)
    {
        _user = user;
    }

    public User User
    {
        get { return _user; }
    }

    public abstract void Execute(UserRepository repository);
}

We also add an abstract method called Execute which every inheriting class must implement -- it's here that we've captured the essence of the switch-case in a much more structural, object-oriented manner.  Instead of a switch statement, we build the same logic structurally into the code by using three classes:

public class DeleteOperation : Operation
{
    public DeleteOperation(User user) : base(user) {}

    public override void Execute(UserRepository repository)
    {
        repository.Delete();
    }
}

public class AddOperation : Operation
{
    public AddOperation(User user) : base(user) {}

    public override void Execute(UserRepository repository)
    {
        repository.Add();
    }
}

public class UpdateOperation : Operation
{
    public UpdateOperation(User user) : base(user) {}

    public override void Execute(UserRepository repository)
    {
        repository.Update();
    }
}

The abstract method now gives us a way of specifying a different action for each "case" by creating another class.  Now our main code can be updated:

private static void Main(string[] args)
{
    // Structural representation of the logic
    List<Operation> inputs = new List<Operation>
    {
        new AddOperation(new User("Charles")),
        new UpdateOperation(new User("Steve")),
        new DeleteOperation(new User("John"))
    };

    UserRepository repository = new UserRepository();

    inputs.ForEach(i => i.Execute(repository));
}

What is our end result?

Improvements in maintainability and cyclomatic complexity

The change in the code itself was very minor; we performed a slight-of-hand and simply moved the three logical branches in the switch into three separate classes instead with each class inherently representing one of the switch cases.  In doing so, however, the cyclomatic complexity for the main program halved to 3 and the the maintainability index increased 6 points, even with such a barebones change.

The overall maintainability index of the entire solution increased 6 points.  Our cyclomatic complexity for the solution did increase, but that's because we've added three new classes which adds to the sum.

There are several other advantages that are easy to extend from this point:

1. It's easier to add new operations.  Instead of adding another case, we simply add another operation class and inherit from the abstract base class.  The logic for that particular operation -- for example, business logic or setup before the operation is invoked -- can be encapsulated in the new class instead of in the case.
2. It's easier to add more logic around the operations.  Because we've removed the invocation from the switch, we can avoid a giant if with deeply nested code as the logic around the operations change.  With a class for each operation, we can add operation specific logic to the class instead.  If we need to add common logic, we can use the base class.
3. It's easier to read.  I think the code is easier to read simply because the level of nesting is now greatly reduced.  McConnell writes in Code Completed, 2nd Edition:
   

   "The smaller part of the job of programming is writing a program so that the computer can read it; the larger part is writing it so that other humans can read it." (McConnell, 733)

4. It's less prone to user error.  By removing the switch and getting away from a string comparison, we've made the solution more resilient to input errors.

Overall, it's a very minor change in the structure of the code (check it out, even the LoC is the same), but even in this most basic of scenarios, it yields clear objective and subjective improvements.  While this is a very basic example of a very specific case, the underlying idea here -- structural representation of logic and flow -- is the real essence of object oriented programming.  The intentionally simplistic example is meant to (hopefully) help surface this concept, but the general idea of refactoring to structural representations is applicable to many different use cases, scenarios, and coding patterns.

Code samples: SampleProcedural.zip and SampleStructuralCode.zip

Browser MapReduce + Charting

Having dabbled in Mongo a bit, I was curious if there was an analog for MapReduce style functionality in browser JavaScript.

I found a small script as a starting point, but made some minor modifications to support array inputs:

// mapper should return an array of [{key:'somekey', value:'somevalue'}]
// reducer should return a single {key:'somekey', value:'somevalue'}
function mapReduce(i, mapper, reducer, property) {
    var intermediate = [];
    var output = [];

    if(i && i.constructor == Array)
    {
        for(var x = 0; x < i.length; x++)
        {
            var value = i[x][property];
            var key = property;

            intermediate = intermediate.concat(mapper(key, value));
        }
    }
    else
    {
        for (var key in i)
        {
            var value = i[key];

            intermediate = intermediate.concat(mapper(key, value));
        }
    }

    var groups = groupBy(intermediate);

    for (var key in groups)
    {
        var values = groups[key];
        output.push(reducer(key, values));
    }

    return output;
}

// list should be [{key:k, value:v}, ....] where key may be repeated.
// returns [{key, [v1, v2, v3...]}, ...] where key is *not* repeated.
function groupBy(list) {
    var ret = {};
    for (var i = 0; i < list.length; i++) {
        var key = list[i].key;
        var value = list[i].value;
        if (!ret[key]) {
            ret[key] = [];
        }

        ret[key].push(value);
    }
    return ret;
}

I then  plugged in my custom map/reduce functions:

// Random data set -- could come from anywhere.
var data = [
    {Country: "US", Type:"B", ProductCode: "001"},
    {Country: "US", Type:"B",  ProductCode: "001.A"},
    {Country: "US", Type:"Z",  ProductCode: "001.B"},
    {Country: "UK", Type:"A",  ProductCode: "002"},
    {Country: "US", Type:"Z",  ProductCode: "003"},
    {Country: "FR", Type:"B",  ProductCode: "003.A"},
    {Country: "DE", Type:"B",  ProductCode: "003.C"},
    {Country: "DE", Type:"T",  ProductCode: "004"},
    {Country: "UK", Type:"R",  ProductCode: "004.R"},
    {Country: "UK", Type:"B",  ProductCode: "005"}
];

// Custom mapper
function _map(key, value)
{
    var result = [];

    result.push({key:value, value:1});

    return result;
}

// Custom reducer
function _reduce(key, values)
{
    var sum = 0;

    for(var i = 0; i < values.length; i++)
    {
        sum += values[i];
    }

    return {key: key, value: sum};
}

Now can I call it like so:

// Basic "group by - count"
var out = mapReduce(data, _map, _reduce, "Country");

This yields the following result:

[{"key":"US","value":4},
{"key":"UK","value":3},
{"key":"FR","value":1},
{"key":"DE","value":2}]

Pretty nifty!  And this data can then be fed into flot for charting purposes.

Sample (with flot example) is attached: MapReduce.zip

Externalizing Build Configuration

While PowerShell is great, I still do a lot of my build automation using plain old batch scripts when it comes to managing my SharePoint development workflow.  Because I do my development outside of my SharePoint environment (develop on my host OS but SharePoint is in my guest OS), it requires some nifty batch scripts to keep the flow tight as no plugins or tools support this development model (dunno why...).

One of the challenges is making it easy to externalize environmental configuration information on a developer-by-developer basis.

In the past, I've relied on having team members create environment variables, but I decided to try out an external configuration file.

It worked out great

The following script reads a file and sets four variables:

@ECHO OFF
ECHO ______________________________________________
ECHO Setting up build environment...
ECHO ______________________________________________
For /F "tokens=1-4* delims=;" %%A IN (..\build-configuration.txt) DO (
SET SERVER=%%A
SET LOGIN=%%B
SET PASSWORD=%%C
SET APPPOOL=%%D
)

ECHO SERVER = %SERVER%
ECHO LOGIN = %LOGIN%
ECHO PASSWORD = %PASSWORD%
ECHO APPPOOL = %APPPOOL%

And the file looks like this:

vm1;administrator;P@ssw0rd;SharePoint - DM App Pool

Now I can use the variables like so:

ECHO ______________________________________________
ECHO Copy to remote server...
ECHO ______________________________________________
IF NOT EXIST \\%SERVER%\_ic\ctmo\ GOTO END

DEL \\%SERVER%\_ic\ctmo\binaries /q /s
XCOPY ..\..\pkgs\*.* \\%SERVER%\_ic\ctmo /Y /I /S

It even works when calling to psexec:

ECHO ______________________________________________
ECHO Start psexec...
ECHO ______________________________________________
::// Deploys the binaries only (doesn't reinstall .wsp).
..\..\tools\sysinternals\psexec.exe \\%SERVER% -u %LOGIN% -p %PASSWORD% -e -d -w C:\_ic\ctmo\binaries cmd /c \\%SERVER%\_ic\ctmo\binaries\gac-install.bat

The best part is that each developer only has to create the text file and all of the environment specific information (like the target SharePoint server) are configured in one tiny file, allowing the automation scripts to be ready for any developer.

A jQuery Scrollbar Replacement

Click here to see the demo page.

I was looking around recently for a jQuery based scrollbar replacement and spent quite some time trying out a few different libraries that I found in a blog post.

I was left quite disappointed as none of the scripts I tried (jScrollPane, ScrollBarPaper, and malihu's custom content scroller) seemed to work well with my use case.  In particular, none of them seemed to work well with content that was set to 100% height.

Malihu's was promising, but as far as coding goes, it wasn't written to be a proper plugin and needed a lot of cleanup.

So after wasting half a day trying out various scrollbar scripts, I ended up rolling my own.  Here are the specs:

• Works with fixed or fluid height containers
• Uses default jQuery UI slider as a scrollbar
• Does not attempt to mimic full scroll bar behavior (I don't want it to be full height, don't need the up/down arrows)
• Responds to mousewheel scrolling
• Easing animation when position changed with a mouse click
• Small - just 72 lines of code including comments and blank lines

A sample screenshot:

Markup wise, the script only requires that you create a structure like so:

<div id="my-id">
    <!--// The scrollable class is required //-->
    <div class="scrollable">
        <!--// Content goes here //-->
    </div>
</div>

Then you can initialize the scrollbars like so:

$(function(){
	/*
		Settings and defaults:

		scrollbarHeight: "300px", // the height of the scrollbar
		scrollbarSize: "6px", // the size of the scrollbar
		positionX: "5px", // the distance from the right of the container
		positionY: "15px", // the distance from the top of the container
		easing: "easeOutQuart", // the named easing effect from jQuery UI
		pace: 20 // affects the mousewheel increment
	*/
	$("#myIdWhatever, #anotherId").prettyScroll();
	$("#yetAnother").prettyScroll({"scrollbarHeight": "400px"});
});

One CSS definition must be added:

/*--- Your container must have an inner DIV with the class "scrollable" ---*/
.scrollable {
	width: 100%;
	height: 100%;
	overflow: hidden;
}

Two basic CSS overrides can optionally be added to make it more scroll bar like (feel free to toy around with this to get your scrollbar to look however you like):

/*--- Override jQuery styles so that there's no color in the slider track ---*/
.scroll-bar .ui-widget-header { background: #fff !important;}
/*--- Override jQuery styles so that the handle is taller ---*/
.scroll-bar .ui-slider-handle {
	width: 1.1em !important;
	height: 2em !important;
}

Since it uses the default jQuery slider widget, you can just use whatever CSS you would normally use to customize the slider here.

You can download the script and demo here: prettyScroll.zip

Update (6/13/2011):  I noticed that this page actually gets a lot of hits in my Google Analytics so I figured it was worth updating with some new script: prettyScroll.20110613.zip

It has some new code that shows how to scroll to an object that's clicked in the scroll pane.  Consider the following markup:

<div id="content3">
    <div class="scrollable">
        <p>Here is some stuff that's before.</p>
        <p>Another sentence.</p>
        <a id="toggler" href="">toggle</a>
        <p class="after" style="display:none">Lorem ipsum dolor sit amet...</p>
        <!-- shortened for brevity -->
    </div>
</div>

When the link "toggle" is clicked, I want to scroll to the link.  I've cut off the content, but assume that it generates a large body of text that requires scrolling once visible.  You can cause it to scroll to the element by triggering a custom event:

$("#toggler").click(function(e){
    e.preventDefault();

    var $this = $(this);

    $this.siblings(".after").toggle();

    $this.parents(".scrollable").trigger("scrollTo", [$this]);
});