Dev|Adept Syndicated Feed

WP7 Series Part 2: Ensuring Blendability with Dependency Injection

noreply@blogger.com (Eric King) — Sun, 29 Jan 2012 03:53:00 +0000

Starting with MVVM

In WP7 Series Part 1 I explained that I wanted to build a Windows Phone application using some basic MVVM principles to maintain 'Blendability'. After tinkering with some options, I've decided to use the MVVM Light Toolkit as the basic framework. It provides some good tools for the toolbox but doesn't otherwise drastically change how I code.

After installing the toolkit and creating a new MVVMLight phone application, open the App.xaml file and you'll find an entry in the Application.Resources section that looks like this:

<Application.Resources>
    <!--Global View Model Locator-->
    <ViewModel:ViewModelLocator x:Key="Locator" 
                                d:IsDataSource="True" />
</Application.Resources>

This 'ViewModelLocator' is the heart of the MVVM Light framework and is meant to be used by every page to find its data context. It does so by assigning a property of the Locator resource to the page's context, like so (at the top of MainPage.xaml):

DataContext="{Binding Main, Source={StaticResource Locator}}"

This line basically says "bind my DataContext to the 'Main' property of the 'Locator' resource". Everything so far is great, and pretty straightforward. A quick look inside the ViewModelLocator.cs file shows that the 'Main' property is a static instance of the MainViewModel.cs class. I'm not going to go into the details of how the ViewModelLocator instanciates the ViewModels, though, because I don't particularly like how it works. I'll show my variation a bit farther down.

Meanwhile, let's glance inside the MainViewModel.cs class. One of the first things I notice is the way DesignTime vs RunTime data is decided.

public MainViewModel()
{
    if (IsInDesignMode)
    {
        // Code runs in Blend --> create design time data.
    }
    else
    {
        // Code runs "for real"
    }
}

With this method, every ViewModel is going to have the same (or very similar) logic duplicated in its constructor. I'd rather have that logic centralized some place else, and have the ViewModel ignorant of its source of data (DesignTime or RunTime). It just uses whatever data it gets.

Enter Dependency Injection

Back to the ViewModelLocator. Since the ViewModelLocator is where the ViewModel classes get instanciated, it seems an appropriate place to decide where to get the data for the ViewModels. I understand that the MVVM Light Toolkit may eventually include a small Inversion of Control container (called SimpleIoc), but I'm comfortable with Ninject, so that's what I ended up using. It takes just a few seconds to install Ninject using NuGet.

In 'Blendable' apps, the concepts of design-time data and run-time data are equally important, so I decided to treat design-time data as an integral part of my data access layer. I like using the Repository pattern, even though its popularity may be waning in some circles, so it makes sense that I should have both design-time and run-time data repositories available.

After creating the repositories (as shown on the right, each implementing the IExampleRepository interface), I created Ninject modules for each of them. You'll notice I created a ViewModelModule; I use that in the ViewModelLocator also.

Now, returning to the ViewModelLocator, I can create a Ninject kernel, and add either the DesignTimeModule or the RunTimeModule depending on the same IsInDesignMode property that the MainViewModel was using. You can see that below in the BuildKernel() method.

My ViewModelLocator now looks like this:

public class ViewModelLocator
{
    private static StandardKernel _kernel;
 
    public ViewModelLocator()
    {
        BuildKernel();
    }
 
    public IMainViewModel Main
    {
        get { return _kernel.Get<IMainViewModel>(); }
    }
 
    private static void BuildKernel()
    {
        _kernel = new StandardKernel(new ViewModelModule());
 
        if (ViewModelBase.IsInDesignModeStatic)
        {
            _kernel.Load(new DesignTimeDataModule());
        }
        else
        {
            _kernel.Load(new RunTimeDataModule());
        }
    }
}

The final piece of the puzzle comes into place by changing the MainViewModel so that it's constructor asks for an IExampleRepository to be injected. The ViewModel itself doesn't care whether it's design-time data or run-time data.

The MainViewModel now looks like this:

public class MainViewModel : ViewModelBase, IMainViewModel
{
    private readonly IExampleRepository _repository;
 
    public MainViewModel(IExampleRepository repository)
    {
        _repository = repository;
    }
 
    public string ApplicationTitle
    {
        get { return "MVVM LIGHT"; }
    }
 
    public string PageName
    {
        get { return "My page:"; }
    }
 
    public string Welcome
    {
        get { return _repository.GetWelcomeMessage(); }
    }
}

The 'Welcome' message (displayed in the middle of the MainPage) is now retrieved through the injected repository, which may be either run-time or design-time data. The end result, in the emulator:

In Visual Studio, design view :

And, finally, in Expression Blend :

So there you have it: one way of injecting design-time and run-time data into a ViewModel using the ViewModelLocator and Dependency Injection, with just a few changes to the out-of-the-box MVVM Light template.

The code for this sample can be found at https://bitbucket.org/devadept/mvvmlightsample/

Read all posts in the WP7-Series

WP7 Series Part 1: To build a Windows Phone 7 app

noreply@blogger.com (Eric King) — Fri, 27 Jan 2012 05:00:00 +0000

And suddenly it's 2012... Where has the time gone?

It's a new year, and I've decided to take on a new challenge by building a Windows Phone 7 app. I've had my Windows phone (an HTC HD7) for over a year, and I absolutely love it. I've not written a XAML app yet, nor a mobile app, but I saw mention of the 30 to Launch challenge a week or so ago, and have decided to give it a try.

I've done the File -> New Windows Phone Project a few times in the past year, but have never felt inspired enough to really delve into creating an app 'for realz', but one thing I do know: I don't want to use the standard out-of-the-box code-behind process. I really want to try to keep to an MVVM model and maintain good 'blendability'.

To that extent, I've tried to do a little research up front to look at some options. I could go the route that @kellabyte had taken during her learning experience and write much of the framework myself. Or, I could try to leverage as much as possible a framework somebody else has written, like Caliburn Micro or MVVM Light.

I watched several of the training videos on Pluralsight, followed by all of the Full Stack series of videos, plus a few others like Laurent Bugnion's Deep Dive MVVM video on Channel 9. I've read through several tutorials, and browsed a bunch of open source code. I figure it's time to get off my butt and write some code.

So, after playing around with a few options, I've settled on a basic app structure that I'm happy with, that uses MVVM Light and Ninject at the core, along with a repository pattern wrapped around SQL CE for data. It allows for easy display of design-time-data in Blend, and adheres to MVVM very well. I'll explain more about the structure in my next post.

Read all posts in the WP7-Series

The organizational mindshift of Agile

noreply@blogger.com (Eric King) — Sat, 06 Aug 2011 22:36:00 +0000

Quite often, adopting Agile requires organizations to change more than expected, and sometimes more than the organizations are willing. I don't think that organizational leaders understand that Agile is not a set of practices or tools from which they can pick and choose, instantly transforming them into an 'Agile Organization'.

Instead, Agile is a set of values; often the values are foreign to those the organization has long held. Embracing these values requires adopting some new practices and tools, for certain, but it must be the values driving the change, not the tools.

I listened to an episode of the Agile Toolkit Podcast the other day, in which host Bob Payne and Kelly Allan discuss Agile and its relationship to W. Edwards Deming's management teachings. At about the 12:00 minute mark, this exchange discusses how much change an Agile transition demands from a traditional, conservative organization:

Kelly - Agile, I think, will help drive even more of Deming's thinking into, and I hope will drive out a lot of the prevailing notions of management as it's practiced.

Bob - Yep.

Kelly - So, what do I mean by that? In part, certain practices like pay for performance and performance appraisals, incentives and rewards and driving in fear and management by quota and management by results and these kinds of things, have no place in the Agile world. Agile rejects that.

Bob - We try.

Kelly - Yes. The rest of the organization, of course, is still stuck in that old management model. So Agile picked up all those things by - so, for example, Deming calls the annual performance appraisal one of the 'deadly diseases' that he lists. His eighth point is 'drive out fear from the organization'. Because if there's fear in the organization, you tamp down innovation, you tamp down experimentation, you tamp down new product development.

Those words, "they have no place in the Agile world", are pretty strong. And I agree with them. But I don't think many business leaders understand how strong the Agile values are when they say they're ready to transition to Agile. What they are wanting is to change a few things here and there, holding their core (often anti-Agile) values steady, and claim victory. They expect software to somehow get built better and faster, as if through some sort of magic applied with the Agile label.

In reality, the management practices of the past are simply dressed up to look like Agile, and continue to be applied as before. See, change is not so hard!

In his book The Art of Agile Development, author James Shore has this to say about the common practice of reporting time usage to management:

If the project is under time pressure - and projects usually are - stakeholders may want to know that the team is using its time wisely. Often, when the team mentions its velocity, stakeholders question it. "Why does it take 6 programmers a week to finish 12 days worth of work? Shouldn't they finish 30 days of work in that time?"

Although I prefer that stakeholders trust the team to schedule its tasks wisely, that trust takes time to develop. In the beginning, I often produce a report that shows how the programmers are using there time. This report requires that programmers track their time in detail, so I stop producing it as soon as possible, typically after a month or two.

In other words, this report, which has probably been a staple report for the organization over the years, is foreign to Agile, which values trusting your team over requiring the team to track time.

To the Agile mind, this time-tracking is waste, as it doesn't lead to working software; in fact it delays the working software. In the Agile point of view, this waste shows that the organization's Agile implementation is broken, and Agile itself demands that it get fixed.

An organization that isn't ready to consider that these practices and processes are broken, that isn't ready to consider rejecting them as Agile does, is simply not ready for Agile.

Agile and the Power of Feedback Loops

noreply@blogger.com (Eric King) — Fri, 22 Jul 2011 03:14:00 +0000

Last month I came across a great article on Wired Magazine titled "Harnessing the Power of Feedback Loops". It reminded me of the importance of one of the basic tenets of Agile programming methodologies, extremely short feedback loops.

The potential of the feedback loop to affect behavior was explored in the 1960s, most notably in the work of Albert Bandura, a Stanford University psychologist and pioneer in the study of behavior change and motivation. Drawing on several education experiments involving children, Bandura observed that giving individuals a clear goal and a means to evaluate their progress toward that goal greatly increased the likelihood that they would achieve it. He later expanded this notion into the concept of self-efficacy, which holds that the more we believe we can meet a goal, the more likely we will do so.

Many times I've seen 'agility' (as it pertains to software development) defined in terms of implementing certain processes and disciplines, or sometimes the lack of disciplines altogether. If you institute a two-week 'sprint', you must be Agile, right? Got a burndown chart? Agile. Don't like documentation? Skip it, and be more Agile!

That misses the point. The way I see it, the single most important aspect of software development agility is feedback. In a truly agile environment, we see feedback loops everywhere. The point of a short work cycle, whether you call them sprints or iterations, or forego them completely with the continuous pull of kanban, is to keep the feedback coming. Daily stand-up? All about meaningful feedback. Pair programming provides the ultimate real-time collaborative feedback between two programmers. Fast running automated unit tests? Feedback.

Why does putting our own data in front of us somehow compel us to act? In part, it’s that feedback taps into something core to the human experience, even to our biological origins. Like any organism, humans are self-regulating creatures, with a multitude of systems working to achieve homeostasis. Evolution itself, after all, is a feedback loop, albeit one so elongated as to be imperceptible by an individual. Feedback loops are how we learn, whether we call it trial and error or course correction. In so many areas of life, we succeed when we have some sense of where we stand and some evaluation of our progress. Indeed, we tend to crave this sort of information; it’s something we viscerally want to know, good or bad. As Stanford’s Bandura put it, “People are proactive, aspiring organisms.” Feedback taps into those aspirations.

It's important to remember, as we put in place all of these processes and tools and practices and policies to become 'agile', that the point of them all is to provide the feedback that we as humans are hard-wired to respond to. Feedback is the secret sauce of agile.

How I Learn

noreply@blogger.com (Eric King) — Sun, 11 Jul 2010 18:28:00 +0000

In the 11th episode of the 37signals Podcast, a listener asks a question of Jason Fried and David Heinemeier Hansson (at the 15:30 mark):

Q: Michael Hopkins would like to hear about what your team does to learn.

A: [Jason] Some people go to conferences, other people just pay attention and observe things. I think that's the best way to learn, just to stay focused on your industry in some ways and see what everyone else is doing and pay attention to the right news sources and learn stuff that way, and to just try it out. That's really the best way to learn anything, to try it and to experiment with stuff.

A: [David] My approach is basically... Whenever I get annoyed about something, that's when I learn. So, I'm annoyed about how a technical process works or something else works, and I don't necessarily know right now how to fix this, so I gotta find out how to fix it. So I gotta learn whatever skills I need to pick up or patterns or whatever else, what have you, to fix things that bug me.

Hearing their answers sparked the question in me ... what do I do to learn?

I really identify with Jason's answer. In many respects, I'm an observer. I like listening, watching, observing, being aware. Taking the time to reason things out. Seeing how others reason. It's how I absorb facts and ideas.

Really learning a topic requires more than one type of observation style, though. Simply reading a book isn't enough. My best learning comes when I combine different observation styles. So, I've developed a multi-pronged learning attack:

Read

There's no shortage of informative, thoughtful, quality reading material out there. Lately I've found myself on a sort of reading renaissance, renewing my childhood love of reading. In the past year or two I've made a concerted effort to maintain a constant reading schedule. I've tried to keep a good mix of fiction and non-fiction, technical and non-technical, purposeful and frivolous. I find that the mere act of reading helps keep the mind engaged. The library is my friend (Remember libraries? Yes, they still exist.)

As for software development, there are a ton of good books out there, from classics like Code Complete, Structure and Interpretation of Computer Programs, and Design Patterns: Elements of Reusable Object-Oriented Software, to new(er) gems like The Pragmatic Programmer, Clean Code: A Handbook of Agile Software Craftsmanship, and The Passionate Programmer: Creating a Remarkable Career in Software Development (Pragmatic Life). For more inspiration, there's a good list of must-read programming books on stackoverflow.

But books aren't the only thing to read. I can't think of a better way to keep up-to-date with the software development industry than a good RSS feed reader and a good list of technical blogs. Develop a reading schedule and maintain some discipline, or else productive reading can quickly turn to wasted time.

Lastly, read source code. There is an abundance of good open-source software out there. Check out Google Code, Codeplex, and GitHub to start.

Listen

I've become a real fan of podcasts. There's no better way for a wallflower like me to listen in on conversations between interesting people discussing interesting topics. Whether it's Scott Hanselman talking about the business of social media or 37signals talking about their design process or Jeff and Joel shooting the breeze about StackOverflow, these are conversations that are going to happen anyway, but we are invited to listen in. You're missing out if you don't. Check out my list of favorite podcasts it you're looking for a place to start. It's a great way to make your commute productive.

Audio books are a good hybrid of the Read and Listen styles. Books that teach programming techniques probably don't translate well to the audio format, but books about the programming industry do. Again, the public library is your friend. There's a ton of content out there that won't cost you a penny to absorb.

Watch

They say sometimes a picture is worth a thousand words. I'm constantly amazed at the amount and quality of video content that's available on the Internet. Sometimes it's one man behind hundreds of video courses (Khan Academy), other times it's an Ivy League university (MIT OpenCourseWare). It might be a mind-opening talk like Seth Godin on quieting the lizard brain or Malcolm Gladwell on spaghetti sauce. There's a ton of vendor-provided how-to videos like ASP.NET MVC Video Tutorials and Ruby on Rails Screencasts. If you can't attend big conferences, many of them record their sessions and provide the content online, like Microsoft Mix and RailsConf.

Paid video learning content can also be very useful. I've recently subscribed to TekPub, which has videos on subjects ranging from ASP.NET MVC2 to Mecurial to Sinatra and more. To get a feel for what the paid content is like, check out their free Coder to Developer series.

Discuss

After reading, hearing, and seeing so much great content, you're bound to have questions and ideas and opinions bounding around in your head. Let them out. Talk about them.

The most obvious place to do so is in your workplace. Strike up a conversation with your development team during your next team meeting or around the water cooler. Set up a "developer day" to get the team together and explore ways of improving processes or integrating new technologies. However you can, the important thing is to get the discussions flowing.

There are plenty of opportunities outside of work, too. Local user groups are an obvious option. But there are also online discussions available on sites like Google Groups, Yahoo! Groups, and LinkedIn.

A great place to ask programming questions is StackOverflow.

Teach

You never know how much you really understand a subject until you (try to) teach it to somebody else. Sometimes it can be humbling, but it's always rewarding. The very act of preparing to teach will lead to a higher understanding the topic.

It's not hard to get started teaching. Here are a few ideas:

Volunteer to give a presentation to your coworkers, or perhaps to a local user group.
Lead a design session that integrates a technique or tool you've just learned.
Log on to StackOverflow and answer some questions.
Teach a child how to make a simple game using Scratch or Alice.
Volunteer at your local school or community center to teach a beginner's programming class

Do

Most importantly, use what you learn. Build things. There's no substitute for hands-on experience.

Improve Your Software Craftsmanship with Apprenticeship Patterns

noreply@blogger.com (Eric King) — Thu, 08 Jul 2010 22:10:00 +0000

I feel that software development, at least the customer-facing business application type of development that I do, is a craft. Although my current official job title is "Software Engineer", I feel less like an engineer and more like a craftsman.

There has already been much debate about this distinction, and I won't repeat it all here. But suffice it to say that the critical difference, to me, lies in how one should go about getting better at their particular flavor of software programming. I tend to agree with this assessment of the continuum of software programming as it relates to the concepts of "art", "craft", "engineering", and "science":

Programming is rarely a science, sometimes engineering, but usually a craft. No example of programming-as-science comes to mind, but there is certainly a lot of science going into programming (codify natural laws found by science, and you have a simulator). Programming is an engineering discipline when the goal is not to add new functionality, but to make existing functionality work to certain quantitative goals. A lot of OS design and database work, for instance, is engineering. Making new functionality is usually a craft, where the result isn't getting something to work at such-and-such a speed but getting something to work at all.

If the types of programs you write tend to be farther to the engineering side of the spectrum, concentrating on speed, efficiency, scalability, interoperability and other quantitative goals, how do you improve your skills? Generally, you increase your algorithmic vocabulary by learning or inventing new algorithmic techniques, or you devise clever ways to harness existing methods in unique and powerful ways. This is mostly an academic exercise, and can be accomplished with traditional educational practices.

But what if your programs are more aligned with qualitative goals? What if the success of your software depends more on being understandable and easy to use than on being ultra-fast or efficient or (gasp) bug free? How do you get better at that? For most of the software that I write, the success of the software depends much more on the qualitative aspects than the quantitative (assuming the engineering quality is reasonable, of course). In my experience, improving one's ability to be successful with that kind of software has shown to be more about practice than about education. You improve the same way you would improve in any other craft.

I recently came across the book Apprenticeship Patterns: Guidance for the Aspiring Software Craftsman.

Are you doing all you can to further your career as a software developer? With today's rapidly changing and ever-expanding technologies, being successful requires more than technical expertise. To grow professionally, you also need soft skills and effective learning techniques. Honing those skills is what this book is all about. Authors Dave Hoover and Adewale Oshineye have cataloged dozens of behavior patterns to help you perfect essential aspects of your craft.

The authors recognize that the most effective way of honing a craft is through the process of apprenticeship. In lieu of a traditional apprenticeship (does anybody know of one?), it is up to you to provide one for yourself. Steps for doing so are provided in the book.

The best part, though, is that you don't even have to buy the book to see what those steps are. The entire contents are freely available through the publisher's website at http://apprenticeship-patterns.labs.oreilly.com/.

There you will find advice on how to:

Unleash Your Enthusiasm
Confront Your Ignorance
Retreat Into Competence
Nurture Your Passion
Find Mentors
Be the Worst
Share What You Learn

and many other patterns to follow on the road to mastery over your craft. Each pattern is presented with its relevant context, what problem the pattern solves, and specific actions you, the apprentice, can take. From the preface:

This book is written for the person who has had a taste of software development and aspires to become a great software developer. You may be a web developer or a medical device programmer, or you may be building trading applications for a financial institution. Or perhaps you have just graduated from high school or college knowing that software is your future.

Although this book was written for newcomers, more experienced developers will benefit from its content as well. People with several years of experience may find themselves nodding their heads in recognition of dilemmas they’ve already faced, and may come away with new insights or at least a new vocabulary to describe the solutions they want to apply for themselves or suggest to their colleagues. Even people with a decade or more of experience—particularly those who may be struggling to navigate their careers—will find inspiration and perspective to counter the siren call of promotion to management.

If that describes you, then you owe it to yourself to (at least) give the online version a look.

Book Review: Linchpin

noreply@blogger.com (Eric King) — Sun, 28 Mar 2010 23:44:00 +0000

I started reading Linchpin: Are You Indispensable? by Seth Godin about the same time as I began reading Rework, which I reviewed in a previous post. So, my reaction to each book will naturally be flavored by my experience with the other.

While Rework is a short, quick read, Linchpin is much more substantial, although still an acceptable 230 pages or so. While Rework shows us how a business can be run effectively with unconventional means, Linchpin tells us how to be successful and unconventional individuals.

The best summary of the message of Linchpin can be found on page 174:

You must become indispensable to thrive in the new economy. The best ways to do that are to be remarkable, insightful, an artist, someone bearing gifts. To lead. The worst way is to conform and become a cog in a giant system.

This is, at some level, rather obvious. Seth spends a lot of time explaining the gift economy and the lizard brain and what he means by making art. And all of this is pretty good stuff. But what it all comes down to is this: If you want to succeed as an employee, as an employer, as a person, you need to stand out from the crowd by exceeding expectations and giving freely your best work, even if less will do. Hardly earth-shattering stuff, but worth repeating.

As Penelope Trunk of Brazen Careerist says:

He is right. Of course. Seth is always right. The problem with all of Seth’s books is that he sets the bar so high with every one of them.

Another problem with his books is that he rarely tells you how he thinks you can achieve those very high bars. Just that you need to meet them. Somehow. This is a problem that Seth himself mentions in Linchpin.

One of my favorite negative reviews of my book Tribes:

"Godin doesn't explain how to go about doing the actual hard groundwork of leadership. He makes it sound like anyone with an idea and a cell phone can rally thousands of people to their cause in minutes if they just realize it's not hard"

My response: Telling people leadership is important is one thing. Showing them step by step precisely how to be a leader is impossible.

Linchpin works the same way. He tells you that being indispensable is important, and why, but stops short of telling you how. That would be impossible. Which makes Linchpin much more of a "get off your butt and do something" inspirational-style book than a "here's a bunch of things you can do to make your life better" self-help book.

Book Review: Rework

noreply@blogger.com (Eric King) — Sun, 14 Mar 2010 05:48:00 +0000

Rework is the latest batch of short-and-sweet business wisdom from Jason Fried and David Heinemeier Hansson, the people behind 37signals (Basecamp, Ruby on Rails, etc.).

A very quick read, Rework is essentially a collection of short blog-like observations about how 37signals runs their (small) business, and how they think you could run a business too if you wanted to. Most of these observations have been expressed by the 37signals team in some form or another already, and those who are already familiar with their philosophy of Signal vs. Noise will find few surprises.

Even so, these things need to be said, and they need to be shared, and I'm glad Jason and David did.

The book in many ways is the authors thumbing their noses at the Harvard MBA "here's how you need to run a real business" crowd. They say "no, you don't have to do it that way" with passages titled:

Ignore the real world
Planning is guessing
Why grow?
Mission statement impossible
Outside money is Plan Z

They advocate counter-intuitive concepts such as:

Underdo your competition
Don't write it down
Pass on great people
Let your customers outgrow you

And they encourage individualism and honesty with sections like:

Don't copy
Own your bad news
How to say you're sorry

All of this is good, if not at least partially obvious. But it's almost as if, in publishing them in book form, the authors are giving ~~entrepreneurs~~ business starters permission to act the way they would like to act, but can't because all of the other business books say otherwise. This is the book that says "We did it this way, and it's working fine for us. Ignore what the suits tell you, and you can do it this way too."

The best pieces of advice, as far as I'm concerned, are the ones where the authors ask us, the readers, to go a bit above and beyond just making money with our businesses, and make the world a better place. In the section "Out-teach your competition", the authors write:

Teach and you'll form a bond you just don't get from marketing tactics. Buying people's attention with a magazine or online banner ad is one thing. Earning their loyalty by teaching them forms a whole different connection. They'll trust you more. They'll respect you more. Even if they don't use your product, they can still be your fans.

Similarly, they advise to "Emulate chefs" like Julia Child, Mario Batali, and Bobby Flay, who share their recipes and techniques with the world with positive effects:

As a business owner, you should share everything you know, too. This is anathema to most in the business world. Businesses are usually paranoid and secretive. They think they have a proprietary this and competitive advantage that. Maybe a rare few do, but most don't. And those that don't should stop acting like those that do. Don't be afraid of sharing.

The ideas of respect and trust, honesty and sharing, appear many times throughout the book, and it's obvious that the overarching feeling the authors are trying to get across is something like "Cut the bullsh*t, be serious, be honest, and be yourself". Hardly anything new, but good advice nonetheless.

While Rework is about 280 pages long, several of the pages are hand-drawn sketches, illustrating the written ideas. Many of them are quite clever.

As explained in Signals vs. Noise podcast Episode #9 (All about Rework), the decision to add the illustrations came late in the editing process, after the authors (in typical 37signals style) cut their written content in half to simplify it, and then found they didn't have enough words to create a book of the right size to fit nicely on a bookstore shelf.

Rather than add words that would dilute the message, they hired Mike Rohde of Rohdesign to provide the illustrations, thus simultaneously giving Rework bookshelf-friendly dimensions and a great style. Mike later wrote a blog post about his experience illustrating Rework. Interesting stuff.

I certainly recommend picking up a copy for yourself and spending a few hours absorbing Jason's and David's advice. If you would like to get a peek at the contents first, head over to the book's website. Here are some of my favorite passages:

"Why don't we just call plans what they really are: guesses."

"Let's retire the term entrepreneur. It's outdated and loaded with baggage. It smells like a members-only club."

"There's a world of difference between truly standing for something and having a mission statement that says you stand for something."

"The problem with abstractions (like reports and documents) is that they create illusions of agreement. A hundred people can read the same words, but in their heads, they're imagining a hundred different things."

"We're all terrible estimators. (...) That's why estimates that stretch weeks, months, and years into the future are fantasies. The truth is you just don't know what's going to happen that far in advance."

"We all know résumés are a joke. They're exaggerations. (...) Worst of all, they're too easy. Anyone can create a decent-enough résumé. That's why half-assed applicants love them so much."

"If you are trying to decide among a few people to fill a position, hire the best writer."

"When you treat people like children, you get children's work. (...) When everything constantly needs approval, you create a culture of non-thinkers. You create a boss-versus-worker relationship that screams, "I don't trust you.""

Finally, a trailer for the book:

More than functional

noreply@blogger.com (Eric King) — Mon, 08 Mar 2010 00:30:00 +0000

I listened to Episode 10 of the Pluralcast podcast the other day, in which David Starr discusses "Reading Code" with Alan Stevens:

A few weeks ago at the MVP Summit in Redmond, I was fortunate enough to run into Alan Stevens, a man my wife refers to as “your southern-gentleman-vegan-hippy friend.” Alan shared with me some new ideas he has around the act of writing (songs or literature) as a metaphor for good practices of software development. The basic idea is that we write a line of code once, and read it many times. Why aren’t we optimizing for the reading part?

The discussion they had struck close to home with me, as it resembled discussions my wife and I have occasionally. She is a fiction writer, and we commonly discuss her craft and how it relates to my craft of software development. In the podcast, Alan Stevens talks about his process of writing code in a way that resembles how he writes prose.

With prose, it's pretty standard practice to write a first-draft with the purpose of just getting ideas down on paper and providing a basic structure, knowing that this draft is never meant to be used or seen by anybody other than the author. The author with then go through and make edits, adding, removing, and changing content, producing more drafts along the way, until, much later in the process, a (semi) final product is revealed. Then, that product will be looked at by an editor or two, and more changes will be made before publication. It's understood that a first-draft is almost never publishing quality, and it's not expected to be able to write a non-trivial product in one go. That's just not how our brains work.

When we write code, however, we seldomly venture past the first draft. We write the code for a module or a feature, verify it's functional, and then we pack away the code with no intention of ever changing it again. I mean, it works, right? There's no such thing as a "first draft". Occasionally there might be a code review session which will result in some edits. But really, how often does that happen?

As it turns out, we always have to come back and read it again sometime. We all know that the code we write spends most of its lifetime in maintenance mode, but we tend to write it with an eye towards functionality only, forgetting about readability. As a result, when we come back to read our code later, we have to spend an inordinate amount of time rebuilding its context. Time we may not have had to spend if we have spent some time moving beyond the purely functional level.

Lately, when I write code, I tend to consider my first run-through as a first-draft, like prose. Even if it ends up working perfectly on the first build, I always intend to make a couple more passes over the code with an eye toward readability. I don't expect to write anything correctly the first time through, even if all my unit tests pass on the first try. I have to think about how I or others will see the code when we read it again 6 months, a year, or (aaagghh!) 3 years from now.

If you find this correlation between writing code and writing prose to be interesting, then you should give the podcast a listen.

The most innovative municipal IT Department in the country

noreply@blogger.com (Eric King) — Fri, 05 Mar 2010 00:20:00 +0000

The most innovative municipal IT Department in the country is here in Scottsdale, Arizona, at least according to the Public Technology Institute:

Public Technology Institute: 2009-2010 Technology Solutions Award Winners

Building on our success from last year, the City of Scottsdale Information Technology department has won six more Technology Solutions Awards (more than any other municipality in the country). We had three projects designated "Winner" in our population category, and three more projects received "Significant Achievement" designation. All of this during a year when the economy caused severe budget cuts in our city, across the state, and the throughout country. It's a great feeling to be involved with such quality work and such good people.

Here is a list of our winning projects, summaries can be read on the PTI page linked above:

The BIG Map (Winner: Sustainability)
Tax Audit Lead Finder (Significant Achievement: Sustainability)
eSubpoena: Creating Efficiencies in the Criminal and Civil Subpoena Process (Significant Achievement: Public Safety Technology)
GIS Disaster Recovery Implementation (Winner: Geospatial Information Systems)
Employee Self Service Portal (Winner: Web and E-Government Services)
QuickPay Utilities Application (Significant Achievement: Web and E-Government Services)

The importance of cultural literacy

noreply@blogger.com (Eric King) — Thu, 04 Mar 2010 18:58:00 +0000

I believe, as do many others, that being a great developer means more than having great technical, code writing skills. I believe this is true because I believe developing great software takes more than simply writing great code.

Even the most technically precise, supremely optimized, highly cohesive, loosely coupled, well documented, easily understandable, utterly attractive code can form the basis of an application that nobody wants to use, particularly if the application was developed without taking into account the needs and desires, likes and dislikes, of the intended audience.

Crafting a well-rounded software application requires something more: “soft skills”, the skills required to be able to converse with, empathize with, relate to, and work with other people, be they your customers, your coworkers, or anybody else who has a stake in the successful outcome of the software you are developing.

As David Starr of Elegant Code recently pointed out, soft skills are actual skills, and they can be learned. He points to an “effective communication pattern” that developers can learn as if they were learning a software design pattern. And there are lots ways for people to learn communication skills, with methods and techniques for:

Establishing personal contact,
Active listening,
Reducing emotional tensions with the partner,
Defending one’s opinion, position, or point of view,
Discussing organization and administration,
Public presentations.

I feel, however, that for such training to be truly effective, one must supplement the methods and techniques with some homework. That homework, in the context of interpersonal communications, I’ve learned to call “cultural literacy".

About 20 years ago I picked up a book called Cultural Literacy: What Every American Needs to Know. It’s still on my bookshelf, and, although much of the topical content is a bit out of date (I see there have been updates), I still refer to it occasionally to this day. From the back cover:

In this forceful manifesto Professor E. D. Hirsch, Jr., argues that children in the United States are being deprived of the basic knowledge that would enable them to function in contemporary society. They lack cultural literacy: a grasp of background information that writers and speakers assume their audience already has. Thus even if a student has basic competence in the English language, he or she has little chance of entering the American mainstream without knowing what a silicon chip is, or when the Civil War was fought.

While the point of the book is to affect childhood education reform, I believe its principles can be applied to the adult workplace, too.

The back cover also asks the reader to test their cultural literacy by putting certain words or phrases into context: “absolute zero”, “sea legs”, “Billy the Kid”, “carpetbagger”, “lame duck”, “Iago”, “tabula rasa”, “Zeitgeist”, etc.

The point of the exercise being to illustrate that there are words, phrases, places, and names used in various forms of communication that bring with them extra meaning wrapped in context. Being culturally literate means being able to recognize that extra meaning and use it to communicate better.

I find myself in an interesting point in my life: not quite 40 years old, I commonly find myself working with folks a generation older than I am, and some who are a generation younger than I am. To the older ones, the terms “Watergate”, “Vietnam”, and “socialism” probably have much greater emotional impact than the same terms do for me, for various reasons. Likewise, “lol”, “friend me”, and “no stalk” have crept into the vocabulary of those much younger than me.

To communicate effectively with those around me, I feel I need to be aware of these contexts; I need to constantly work on my cultural literacy. The best developers among us are those who can understand and communicate with others, and the best communicators are those who are culturally literate.

Abstractions, Abstractions, Pile Them On

noreply@blogger.com (Eric King) — Sun, 14 Feb 2010 02:08:00 +0000

In my modest experience as a web developer using ASP.NET, I have gone through several stages of comfort and happiness with Web Forms, most of which I assume are pretty common:

Amazement at how little code or markup you need to write in order to spit out a bunch of html
Confusion over this “Postback” thing
Slowly growing comfort with the “Page Life Cycle” and its foibles
Eagerness to use more controls, especially those new-fangled “Ajax” ones
Happiness over how quickly pretty good applications could be written
Frustration at the quality of the html that gets spit out
More frustration over state-management (view state? session variables? hidden form fields? cookies? client-side caching? server side caching? AARRGGHH!!)
Yet more frustration with the hoops you have to jump through with the Page Life Cycle
Even more frustration with the Update Panel and the general clumsiness of ASP.NET Ajax
Hope that tools like jQuery will help deal with the above frustrations

You may have noticed a trend. :-) Like many, I think I have grown slowly weary of the idiosyncrasies of the Web Forms engine and its “Leaky Abstraction” problems. In our zeal to abstract away the complexities of a naturally stateless web environment, we’ve accepted abstractions piled upon abstractions piled upon more abstractions. I can’t help but feel we’ve arrived at a point where, despite creating abstractions to simplify web development, the weight of the abstractions (or, more precisely, the weight of the leaks) have complicated things more than they’ve helped.

Of course, I’m not the first to realize that ASP.NET is a leaky abstraction. And I’m certainly not suggesting that the abstractions shouldn’t be respected. On the contrary, I understand that the tall abstraction pile helps us build better software. But, as Eric Sink says:

This is what programmers do. We build piles of abstractions. We design our own abstractions and then pile them up on top of layers we got from somebody else. Abstractions can be great. We use them because they save us a lot of time. But abstractions can also cause lots of problems. They're never perfect, as Joel Spolsky explains in his excellent article on "The Law of Leaky Abstractions".

But you can't have the benefits of an abstraction without its risks. We need to make wise decisions about our piles of abstractions.

So, we’ve built layer on layer of abstractions, some layers created solely to fix problems created by other abstractions. And it can get very confusing just keeping them straight.

Consider this recent question on StackOverflow concerning view state and dynamically loaded controls. The developer is using an Update Panel (abstraction of Ajax functionality) holding a Panel (abstraction of a div) on a page with manually updated view state (abstraction of application state). Sometime during the page lifecycle, the developer wants to add dynamically loaded controls (abstraction of HTML elements), but during the postback (abstraction of a stateful event), the controls lose their state. He’s using somebody’s example as a reference, but with a slight difference. What can he do?

This entire situation exemplifies what happens when we pile too many abstractions on top of one another, such that we end up with so many leaks that we don’t know how to resolve them. Yet, what’s our first impulse when trying to help? We suggest to try yet one more abstraction. This, to provide page functionality that (if done with different tools) probably wouldn’t need any of the abstraction layers that are getting in the way.

I can certainly see, therefore, the attraction that many web developers have to ASP.NET MVC. It, unlike web forms, accepts the fact that the web is primarily a stateless environment. It is able, therefore, to strip away many of the abstractions we’ve built to simulate a stateful environment. To be fair, many of the frustrations we have with the current version of web forms are being addressed with ASP.NET 4.0. And MVC adds a few new abstractions of its own. But still…

MVC has a few paradigms that may be tough to learn for those whose experience is entrenched in web forms. Gone are the training wheels, and that scares some, and frustrates others (I’ve got to learn something else now?). On the whole, though, using MVC feels like a more natural way to develop web applications. It sheds many of the abstraction layers that web forms has built up for us, and in turn feels less complicated.

At least, so far. Let’s see how long that lasts. :-)

GPFKURH6UEK9

Developer Soft Skills

noreply@blogger.com (Eric King) — Fri, 12 Feb 2010 04:05:00 +0000

I listened to a good podcast episode of Deep Fried Bytes (Episode 44) the other day:

In this episode Keith and Woody sat down with Brian Prince, Developer/Architect Evangelist for Microsoft, to discuss the soft skills developers and software engineers need. Brian has been speaking at conferences about soft skills for many years. In true Deep Fried fashion this show is chalk full of stories. The guys discuss tips for handling one's career as well as life work balance, sales and communication.

Soft skills are social, interpersonal, and leadership skills that programmers (and many other people, for that matter) sometimes neglect to develop. I strongly believe that it’s impossible to be a truly adept developer without cultivating the skills involved with effective interpersonal relationships. We are, after all, people writing code for other people.

Anyhow, the discussion between the Deep Fried Bytes guys and Brian Prince touched on a lot of important ‘soft skill’ issues. It’s well worth the listen.

Using ELMAH with multiple applications

noreply@blogger.com (Eric King) — Tue, 09 Feb 2010 05:08:00 +0000

I’ve been using ELMAH a lot lately, and have it deployed to multiple ASP.NET applications. As I’ve said before, I love it. It’s certainly easy to set up and useful for each application to have an error log of its own.

However, sometimes I want to see a consolidated list of errors across all of those applications. Here are a few of the things I’ve done to create what I call a “Master” ELMAH error log viewer.

First, the easy part. Each of the applications that I’ve deployed are connected to the same SQL Server database, prepared using the standard ELMAH configuration. All of them log to the same database.

The ELMAH viewer page HTTP handler, however, is designed to filter the errors by application. It does this by inferring the application name (or getting it from the config file, if you’ve specified it there), and then sending that application name to the database as a parameter for the ELMAH_GetErrorsXML and ELMAH_GetErrorXML stored procedures. The stored procedures have a WHERE clause in the SELECT statement that filters the errors. This is great for the applications individually, but we have to override that behavior if we want to have a consolidated view.

To start, I created two additional stored procedures in the database called ELMAH_GetErrorsXML_Master and ELMAH_GetErrorXML_Master. These sprocs are identical to the standard ELMAH sprocs, except I’ve removed the ‘@Application’ parameter and the ‘WHERE [Application] = @Application’ clauses.

Next (this requires downloading the source code, editing it, and recompiling), I created a ‘SQLMasterErrorLog.cs’, based on the existing ‘SQLErrorLog.cs’ class. I edited the GetErrorXml() and GetErrorsXML() methods to match the new sprocs I created, removing the @Application parameter.

For example, this:

public static SqlCommand GetErrorXml(string appName, Guid id)

SqlCommand command = new SqlCommand("ELMAH_GetErrorXml");

command.CommandType = CommandType.StoredProcedure;

SqlParameterCollection parameters = command.Parameters;

parameters.Add("@Application", SqlDbType.NVarChar,

_maxAppNameLength).Value = appName;

parameters.Add("@ErrorId", SqlDbType.UniqueIdentifier).Value = id;

return command;

became this:

public static SqlCommand GetErrorXml(string appName, Guid id)

SqlCommand command = new SqlCommand("ELMAH_GetErrorXml_Master");

command.CommandType = CommandType.StoredProcedure;

SqlParameterCollection parameters = command.Parameters;

parameters.Add("@ErrorId", SqlDbType.UniqueIdentifier).Value = id;

return command;

GetErrorsXML() got the same treatment. I also updated the <summary> description and the ‘Name’ property to reflect the changes I had made.

Next, I changed the ErrorLogPage.cs file to display an extra column in the log viewer table for the Application Name. In the "’RenderErrors()” method, I added these lines (top line only):

headRow.Cells.Add(FormatCell(new TableHeaderCell(), "App", "app-col"));

headRow.Cells.Add(FormatCell(new TableHeaderCell(), "Host", "host-col"));

and

bodyRow.Cells.Add(FormatCell(new TableCell(), error.ApplicationName, "app-col"));

bodyRow.Cells.Add(FormatCell(new TableCell(), error.HostName, "host-col"));

After saving and compiling, I had a new elmah.dll that contains a “SQLMaster” error log.

The final step was creating a web application to hold the new ELMAH viewer. I made an empty ASP.NET application, with nothing in it but a Default.aspx file that really only exists to autoforward to the errors.axd handler. With one small tweak to the standard configuration, I was off and running:

<errorLog type="Elmah.SqlMasterErrorLog, Elmah" connectionStringName="elmah"/>

A few days with my son and Python

noreply@blogger.com (Eric King) — Thu, 04 Feb 2010 05:03:00 +0000

I’ve had the Hello World! Computer Programming for Kids and Other Beginners book for about a week now, and my son and I have spent a few hours dabbling with it. So far I’d have to say that I’m pretty pleased with his level of interest.

The first few chapters are designed to get the reader to the general concept of computer programming and how to use the development environment (which is IDLE, a basic Python interactive shell). The book walks you through a bunch of basic string and number manipulating commands, and then the first chapter ends by asking the reader to type in a slightly longer program (about 18 lines) to run as a demo of concepts to be learned later in the book. The program, a pirate-themed random-number guessing game, is then run in the IDLE shell.

Watching my son do this reminded me of when I was a kid, typing a 100+ line BASIC program into a friend’s Commodore64 cassette-tape drive, executing, and hoping I hadn’t made a typo. Except now, a lot of the tedium has been removed and the feedback loop is so much faster. Ahh, kids these days just don’t realize how easy they have it…

Anyhow, as ‘cool’ as the pirate-speak is in the sample code (“What's yer guess?” and “Avast! Ye got it! Found my secret, ye did!”) my son’s interest rose exponentially once I suggested that it was his program and he could change the words if he wanted to. He decided to substitute a Pokémon theme, and spent the next 45 minutes modifying the code appropriately. Nice.

To spur my own learning and keep him interested, I created a text file with a list of all of the Pokémon characters (my some told me there are 150 of them, it turns out there are 493) and used it as a resource for another version of the number-guessing game. We were now able to have a Pokémon identify itself by name and the player guesses its ‘number’. My son spent another 45 minutes or so playing this one. Next we made another version of the app which lets the player type in the character’s name and the program will find its number in the character list. Big hit.

So far it's been baby steps for both of us, but it’s been fun. While trying to find ways to incorporate his schoolwork into the programming exercises, I made up a little quiz-game with the States and their Capital Cities. He loves it. I hope his interest continues.

I’m also enjoying learning Python. I can remember how I felt a few years ago when I made the transition from writing VBA and VB6 and ‘classic’ ASP code to writing C# and ASP.NET. Everything seemed much more stiff and restrictive, what with all of the curly braces and semicolons all over the place. One character out of place and the whole build breaks. But now I’m used to it. Dare I say, I’m almost dependent on it.

Python, however, seems so much more loose. It’s dynamically typed, and code blocks are denoted using whitespace rather than the (oh so comforting) curly braces. I don’t feel so much free writing Python code as I feel naked. When defining a class, where do I put the property definitions? “Properties?” replies Python. “We don’t need no stinking properties!”. The way the code looks is fairly comfortable, although the sense of elegance hasn’t quite hit me yet.

I feel good about it, though. Perhaps after working my way through Hello World! with my son I’ll go a bit deeper. Maybe I can look forward to tackling Dive Into Python and/or Django.

Hello World!

noreply@blogger.com (Eric King) — Sun, 24 Jan 2010 16:19:00 +0000

After listening to Scott Hanselman interview 10-year old Carter Sande and his dad Warren on a recent Hanselminutes episode, I skipped over to YouTube and watched him give an introduction to PythonCard (see below). He's one precocious kid.

He and his dad have written a book called Hello World! Computer Programming for Kids and Other Beginners. I decided to buy the book for my sons and see how they like it.

We've dabbled in some programming together previously, using Scratch. They seemed somewhat interested, but being typical 6 or 8 year-old boys, their attention drifted and I haven't seen them working with Scratch recently. The Hello World! book uses Python, which is very different from the graphics-oriented Scratch, so I have no idea how if their interest in programming will come back. We'll see.

(Not that I necessarily want my children to follow in my computer-programming footsteps, but I think that learning basic programming concepts is important in the same way as learning basic math concepts.)

Anyhow, I ordered the book from Manning.com with the 40% discount code you can find on the Hanselminutes podcast page. It's good until January 31st.

New Year, Fresh Start

noreply@blogger.com (Eric King) — Sun, 24 Jan 2010 06:40:00 +0000

Well, another year has rolled around, and before I know it the first month has already blown by. How time flies!

I started blogging last year and, not being much of a writer, I decided to try to inspire some topics by inspecting and changing the code of the very tool I was using to blog. So I started using BlogEngine.net both as a blogging platform and as a refactoring experiment.

As you can see, I'm not doing that any more. As I delved deeper into the BlogEngine.net code, refactoring as I went, I was also learning more about SOLID programming principles such as the Dependency Inversion Principle and the Single Responsibility Principle. As I became more familiar with the BlogEngine.net codebase, I was also becoming more comfortable with Domain Driven Design concepts such as Entities and Repositories.

The result was that, over time, I could see that BlogEngine.net was not written in a manner that accommodates SOLID or DDD strategies. Short of completely gutting the project and rewriting core components from scratch, there was not going to be any Inversion of Control. Unit testing is next to impossible.In the meantime, ASP.NET MVC was released, and is now closing in on a v.2 release. I have a couple of side-projects I'd like to build, and I guess I'm just ready to move on.

So, as of this post, I've moved over to Blogger, at least for now. :-) I don't feel that my experiment with BlogEngine.net was a failure, though. On the contrary; I learned a lot. Being exposed to different programming styles is a good thing, and I feel a greater appreciation for the styles I've chosen. And while BlogEngine.net works great for those who've written it, it's ultimately not for me.

(For the record, this is my 3rd blogging platform in 3 years, spanning a total of 14 posts. Note to self: write more.)

Tickle Me ELMAH

noreply@blogger.com (Eric King) — Sun, 06 Sep 2009 18:48:00 +0000

I came across a utility the other day that, in my opinion, just Gets It Right™. It’s easy to install, easy to configure, easy to use, and it’s got just the features you need, nothing more. It gets out of your way, and unobtrusively does its work. It’s free and open source. What more can you ask for?

The utility is called ELMAH. It’s an exception logging tool, and it’s unfortunate name is an acronym for “Error Logging Modules And Handlers”. Its Google Code site at http://code.google.com/p/elmah/ describes itself as:

ELMAH (Error Logging Modules and Handlers) is an application-wide error logging facility that is completely pluggable. It can be dynamically added to a running ASP.NET web application, or even all ASP.NET web applications on a machine, without any need for re-compilation or re-deployment.

Once ELMAH has been dropped into a running web application and configured appropriately, you get the following facilities without changing a single line of your code:

Logging of nearly all unhandled exceptions.

A web page to remotely view the entire log of recoded exceptions.

A web page to remotely view the full details of any one logged exception.

In many cases, you can review the original yellow screen of death that ASP.NET generated for a given exception, even with customErrors mode turned off.

An e-mail notification of each error at the time it occurs.

An RSS feed of the last 15 errors from the log.

I remember first reading about ELMAH a few months ago on Scott Hanselman’s blog, which led me to a Phil Haack blog post and then to Jeff Atwood’s Coding Horror. All of them have nothing but good things to say about ELMAH, and how easy it is to get up and running.

A couple of weeks ago I decided to get off my rump and see what all of the hoopla was about. Since I’ve been refactoring the BlogEngine.NET engine that runs this site, I’ve often been frustrated with the lack of error logging (and unit tests, but that’s another post). I’ve used log4net before, but I have never liked the effort it takes to integrate it into an existing codebase. ELMAH, however, seems to be a perfect fit with the “easy to install, easy to use” attitude of BlogEngine.

The ELMAH help pages along with Scott Hanselman’s and Phil Haack’s posts above give a lot of step-by-step installation instructions, so I’m not going to rehash them here. But, here’s a quick overview of what to expect if you want a basic, fully functional ELMAH installation:

Download the ELMAH binaries
Copy the ELMAH dll into your bin directory
Add a few entries to your web.config file
That’s it. There is no step 4.

Since I’m still using the out-of-the-box XML provider for BlogEngine, I simply added an “errors” folder in the App_Data directory. (I guess that can be your step 4.) I pointed my ELMAH configuration to save the XML log files in that directory, and everything just works.

I secured the log viewer page as described in Phil Haack’s post, and I then edited the web.sitemap file to add a new admin link pointing to it. That way, when I’m logged in, I can go straight to the errors page with a single click.

Less than 10 minutes later, and I have a pretty good, basic level of exception logging for BlogEngine, without having to add a single line of code. But, for a little context, be sure to read Atif Aziz’s response to Phil Haack’s post. Atif is the developer of ELMAH, and among other things, he says:

It's definitely not a general-purpose logging framework nor one for instrumentation. It only logs unhandled exceptions in a non-invasive way (speaking code-wise). I usually discourage people from using it to log errors in their catch blocks because that purpose is served better by existing tracing facilities and frameworks and often by actually handling the offending case gracefully in code.

Even so, I think it’s a great tool to have in your ASP.NET toolbox.

Solo refactoring

noreply@blogger.com (Eric King) — Sun, 23 Aug 2009 04:33:00 +0000

In my most recent post I described a recent refactoring exercise. Refactoring can be a dangerous exercise, if not done properly. Any time you alter code, there is a risk that a bug or performance issue can be introduced. Hence the strong attraction to the “if it ain’t broke, don’t fix it” rule of thumb.

But if done correctly, refactoring mercilessly is a very strong practice. According to Martin Fowler:

Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior. Its heart is a series of small behavior preserving transformations. Each transformation (called a 'refactoring') does little, but a sequence of transformations can produce a significant restructuring. Since each refactoring is small, it's less likely to go wrong. The system is also kept fully working after each small refactoring, reducing the chances that a system can get seriously broken during the restructuring.

My intent in refactoring the code was to make it more readable and understandable, without changing its external behavior. No adding features, no removing features, no bug fixes. And certainly no new bugs.
I think I was pretty successful with the code cleanup part, but I was not careful enough. Just a handful of hours after I posted, a reader named Ivan submitted a comment pointing out a case I had neglected to handle.

A case which was handled in the code I changed during my refactoring. I had broken the cardinal rule: I had introduced a bug.

Ivan, My New Pair

So why did this happen? It would be easy to say that I was just too careless. I worked alone, and didn’t ask for my code to be reviewed. Some would say I shouldn’t have refactored otherwise working code, anyway. I think these things just happen; bugs happen, even to the best of us.

But there are things we can do to minimize the chance of these bugs seeing the light of day. One of the things our group has been doing more of in the last year or two is pair programming. Having a second programmer next to you, keeping you on track by thinking strategically while you’re in tactical mode, helps to keep little errors from sneaking in. On the day I did this refactoring, my programmer pair was unavailable. Rather than try to implement a new feature solo, I thought it would be safer to pay down some technical debt with some small refactorings.

Anyway, long story short, the small oversight I made would probably have been caught nearly immediately if I had been pair programming at the time. In this case, Ivan from the Ukraine, across time and space, was my virtual pair for a few minutes. He noticed one small thing, made one small comment, and put me back on track. Thanks Ivan.

Test, Test, Test

Another way to severely reduce the risk of making breaking changes is with a good set of unit tests. If you have intention revealing code, and those intentions are explicitly asserted by your tests, it’s very hard to unknowingly break things by refactoring. That big red “test failed” indicator stares you right in the face.
Our group, as are most (I suspect), is still maturing in our unit testing methodology. I personally am still not very comfortable with Test Driven Development, but I try to keep all of my code as much under test as possible. In this particular case, there was no test wrapped around the particular situation I had missed and Ivan had pointed out. There is now, though. The next person (pair) who decides to refactor this particular code will have the benefit of a test explicitly reminding them of this case, and each of the other rules the class must follow. The tests are the executable specification.

He can be taught

So what I have learned? I learned that I need to be more careful when changing other people’s code. :-) I learned that pair programming is valuable even for simple code, and even across 10,000 kilometers. I learned that good tests help not only when first writing the code under test, but perhaps even more when someone else comes along to refactor it. I learned to triple-check any code I post on my blog. And I learned there are some very nice people out there willing to spend a few moments to help a stranger.

To be honest, I thought I knew all of these things before, but I guess it takes a little reminder now and then to refresh one’s memory. That’s probably the most important lesson of the day.

Intention Revealing Code

noreply@blogger.com (Eric King) — Thu, 20 Aug 2009 00:24:00 +0000

I just watched the video of Robert Martin’s Norwegian Developers Conference presentation titled “Clean Code III - Functions”. In his hour-long talk, he talks about methods you can use and principles you should follow to make your code more understandable and more readable. He also show some sample code that is difficult to understand at first reading, and then some refactorings of that code that increase its understandability.

I won’t go into the details of his talk; you should watch it yourself. It’s well worth the hour-long investment. But his refactoring example reminded me of a refactoring exercise that I recently did.

The code in question is a class that provides date-based services such as calculating X number of business days before or after a given date, and determining whether a specific calendar date is a business date or a holiday. To do so, the service must follow these rules for determining holidays:

Independence Day, July 4

Labor Day, first Monday in September

Thanksgiving Day, fourth Thursday in November

Day after Thanksgiving Day, fourth Friday in November

Christmas Day, December 25

New Year's Day, January 1

Martin Luther King, Jr. Day, third Monday in January

President's Day, third Monday in February

Memorial Day, last Monday in May

Holidays falling on Saturday will be observed on Friday and holidays falling on Sunday will be observed on Monday.

We’ve got nine holidays, some determined by a particular position within a month (i.e. “fourth Thursday in November”), and some determined by a particular calendar date (i.e. “July 4th”). The holidays determined by calendar date may need to be adjusted by a day if the date falls on a weekend. The list of holidays is static; it’s not likely to change anytime soon.

The basic interface of the class is:

namespace Your.Namespace.Here

public interface IDateService

DateTime CalculatePriorBusinessDate(DateTime startDate, int numberOfBusinessDays);

DateTime CalculateSubsequentBusinessDate(DateTime startDate, int numberOfBusinessDays);

bool IsBusinessDate(DateTime calendarDate);

bool IsHolidayDate(DateTime calendarDate);

The implementation of the class is about 270 lines of code, including comments. You know how I feel about comments. Subtract them out, and you’re left with about 230 lines.

   1: namespace Your.Namespace.Here

   2: {

   3:     public class  DateService : IDateService

   4:     {

   5:         private string error = string.Empty;

6:

   7:         public DateService()

   8:         {

   9:         }

10:

  11:         /// <summary>

  12:         ///  Determines if a calendar date is a valid business date.

  13:         /// </summary>

  14:         /// <param name="calendarDate">This is any calendar date</param>

  15:         /// <returns>returns true, if calendar date is a valid business date, else returns false</returns>

  16:         ///

  17:         public bool IsBusinessDate(DateTime calendarDate)

  18:         {

  19:             bool isBusinessDate = false;

  20:             // Weekends and Holidays are not business days

  21:             if (IsWeekend(calendarDate) || IsHoliday(calendarDate))

  22:             {

  23:                 isBusinessDate = false;

  24:             }

  25:             else

  26:                 isBusinessDate = true;

  27:             return isBusinessDate;

  28:         }

29:

  30:         /// <summary>

  31:         ///  Determines if a calendar date is a valid Holiday.

  32:         /// </summary>

  33:         /// <param name="calendarDate">This is any calendar date</param>

  34:         /// <returns>returns true, if calendar date is a valid holiday, else returns false</returns>

  35:         ///

  36:         public bool IsHolidayDate(DateTime calendarDate)

  37:         {

  38:             bool isHolidayDate = false;

39:

  40:             if (IsHoliday(calendarDate))

  41:             {

  42:                 isHolidayDate = false;

  43:             }

  44:             else

  45:                 isHolidayDate = true;

  46:             return isHolidayDate;

  47:         }

48:

  49:         /// <summary>

  50:         /// Calculates prior business date

  51:         /// </summary>

  52:         /// <param name="startDate">This is the starting business date to calculate</param>

  53:         /// <param name="numberOfBusinessDays">This is the number of prior business days requested;Must be positive integer</param>

  54:         /// <returns>The calculated business date requested based on number of business days</returns>

  55:         ///

  56:         public DateTime CalculatePriorBusinessDate(DateTime startDate, int numberOfBusinessDays)

  57:         {

  58:             if (numberOfBusinessDays < 0)

  59:             {

  60:                 error = "Prior Business Days must be a positive number";

  61:                 throw new Exception(string.Format("reason : {0}", error));

  62:             }

  63:             return CalculateBusinessDate(startDate, numberOfBusinessDays * -1);

  64:         }

65:

  66:         /// <summary>

  67:         /// Calculates subsequent business date

  68:         /// </summary>

  69:         /// <param name="startDate">This is the starting business date to calculate</param>

  70:         /// <param name="numberOfBusinessDays">This is the number of subsequent business days requested;Must be positive integer</param>

  71:         /// <returns>The calculated business date requested based on number of business days</returns>

  72:         ///

  73:         public DateTime CalculateSubsequentBusinessDate(DateTime startDate, int numberOfBusinessDays)

  74:         {

  75:             if (numberOfBusinessDays < 0)

  76:             {

  77:                 error = "Subsequent Business Days must be a positive number";

  78:                 throw new Exception(string.Format("reason : {0}", error));

  79:             }

  80:             return CalculateBusinessDate(startDate, numberOfBusinessDays);

  81:         }

82:

  83:         private DateTime CalculateBusinessDate(DateTime startDate, int numberOfDays)

  84:         {

  85:             int busDays = 0;

  86:             DateTime curDate = startDate;

  87:             int incr = 1;

  88:             if (numberOfDays < 0)

  89:                 incr = -1;

  90:             while (busDays < Math.Abs(numberOfDays))

  91:             {

  92:                 curDate = curDate.AddDays(incr);

93:

  94:                 // Weekends and Holidays are not business days

  95:                 if (IsWeekend(curDate) || IsHoliday(curDate))

  96:                 { }

  97:                 else

  98:                     busDays = busDays + 1;

  99:             }

 100:             return curDate;

 101:         }

 102:

 103:         private bool IsWeekend(DateTime curDate)

 104:         {

 105:             bool isOnWeekend = false;

 106:

 107:             //Check for weekend date

 108:

 109:             if (curDate.DayOfWeek == DayOfWeek.Saturday || curDate.DayOfWeek == DayOfWeek.Sunday)

 110:                 isOnWeekend = true;

 111:

 112:             return isOnWeekend;

 113:         }

 114:

 115:         private bool IsHoliday(DateTime curDate)

 116:         {

 117:             bool returnValue = false;

 118:

 119:             // Check for New Year's, Christmas, and Independence Day

 120:

 121:             if (curDate.Month == 1 && curDate.Day == 1)

 122:                 returnValue = true;

 123:             if (curDate.Month == 7 && curDate.Day == 4)

 124:                 returnValue = true;

 125:             if (curDate.Month == 12 && curDate.Day == 25)

 126:                 returnValue = true;

 127:

 128:             // Friday is a holiday if actual holiday falls on Saturday

 129:

 130:             if (curDate.DayOfWeek == DayOfWeek.Friday)

 131:             {

 132:                 if (curDate.Month == 12 && curDate.Day == 31)

 133:                     returnValue = true;

 134:                 if (curDate.Month == 7 && curDate.Day == 3)

 135:                     returnValue = true;

 136:                 if (curDate.Month == 12 && curDate.Day == 24)

 137:                     returnValue = true;

 138:             }

 139:

 140:             // Monday is a holiday if actual holiday falls on Sunday

 141:

 142:             if (curDate.DayOfWeek == DayOfWeek.Monday)

 143:             {

 144:                 if (curDate.Month == 1 && curDate.Day == 2)

 145:                     returnValue = true;

 146:                 if (curDate.Month == 7 && curDate.Day == 5)

 147:                     returnValue = true;

 148:                 if (curDate.Month == 12 && curDate.Day == 26)

 149:                     returnValue = true;

 150:             }

 151:

 152:             // Test for Monday Holidays

 153:

 154:             if (curDate.DayOfWeek == DayOfWeek.Monday)

 155:             {

 156:                 if (curDate.Month == 1 && WhichMonday(curDate) == 3)

 157:                     returnValue = true;

 158:                 if (curDate.Month == 2 && WhichMonday(curDate) == 3)

 159:                     returnValue = true;

 160:                 if (curDate.Month == 9 && WhichMonday(curDate) == 1)

 161:                     returnValue = true;

 162:                 if (curDate.Month == 5 && LastMondayInMay(curDate) == true)

 163:                     returnValue = true;

 164:             }

 165:

 166:             // Test for Thanksgiving

 167:

 168:             if (curDate.DayOfWeek == DayOfWeek.Thursday)

 169:             {

 170:                 if (curDate.Month == 11 && WhichThursday(curDate) == 4)

 171:                     returnValue = true;

 172:             }

 173:             // Test for Friday after Thanksgiving

 174:

 175:             if (curDate.DayOfWeek == DayOfWeek.Friday)

 176:             {

 177:                 if (curDate.Month == 11 && WhichFriday(curDate) == 4)

 178:                     returnValue = true;

 179:             }

 180:             return returnValue;

 181:         }

 182:

 183:         private int WhichMonday(DateTime curDate)

 184:         {

 185:             return WhichDay(curDate, DayOfWeek.Monday);

 186:         }

 187:

 188:         private int WhichDay(DateTime curDate, DayOfWeek day)

 189:         {

 190:             int which = 0;

 191:             DateTime firstDay = GetFirstDay(curDate, day);

 192:             while (firstDay <= curDate)

 193:             {

 194:                 which += 1;

 195:                 if (curDate == firstDay)

 196:                     break;

 197:                 firstDay = firstDay.AddDays(7);

 198:                 if (firstDay.Month != curDate.Month)

 199:                 {

 200:                     throw new Exception("WhichDayError");

 201:                 }

 202:             }

 203:             return which;

 204:         }

 205:

 206:         private DateTime GetFirstMonday(DateTime curDate)

 207:         {

 208:             return GetFirstDay(curDate, DayOfWeek.Monday);

 209:         }

 210:

 211:         private DateTime GetLastMonday(DateTime curDate)

 212:         {

 213:             return GetLastDay(curDate, DayOfWeek.Monday);

 214:         }

 215:

 216:         private DateTime GetFirstDay(DateTime curDate, DayOfWeek day)

 217:         {

 218:             DateTime myDate = new DateTime(curDate.Year, curDate.Month, 1);

 219:             while (myDate.DayOfWeek != day)

 220:             {

 221:                 myDate = myDate.AddDays(1);

 222:             }

 223:             return myDate;

 224:         }

 225:

 226:         private DateTime GetLastDay(DateTime curDate, DayOfWeek day)

 227:         {

 228:             DateTime myDateTemp = curDate.AddMonths(1);

 229:             DateTime myDate = new DateTime(myDateTemp.Year, myDateTemp.Month, 1);

 230:             myDate = myDate.AddDays(-1);

 231:             while (myDate.DayOfWeek != day)

 232:             {

 233:                 myDate = myDate.AddDays(-1);

 234:             }

 235:             return myDate;

 236:         }

 237:

 238:         private bool LastMondayInMay(DateTime curDate)

 239:         {

 240:             bool rv = false;

 241:             DateTime curMonday = GetLastMonday(curDate);

 242:             if (curMonday == curDate)

 243:                 rv = true;

 244:             return rv;

 245:         }

 246:

 247:         private int WhichThursday(DateTime curDate)

 248:         {

 249:             return WhichDay(curDate, DayOfWeek.Thursday);

 250:         }

 251:

 252:         private DateTime GetFirstThursday(DateTime curDate)

 253:         {

 254:             return GetFirstDay(curDate, DayOfWeek.Thursday);

 255:         }

 256:

 257:         private int WhichFriday(DateTime curDate)

 258:         {

 259:             return WhichDay(curDate, DayOfWeek.Friday);

 260:         }

 261:

 262:         private DateTime GetFirstFriday(DateTime curDate)

 263:         {

 264:             DateTime myDate = new DateTime(curDate.Year, curDate.Month, 1);

 265:             while (myDate.DayOfWeek != DayOfWeek.Friday)

 266:             {

 267:                 myDate = myDate.AddDays(1);

 268:             }

 269:             return myDate;

 270:         }

 271:     }

 272: }

Functionally, this code is fine. It meets all of the requirements, can correctly determine if a particular calendar date is a holiday, can correctly determine a previous or subsequent business date. But… It’s not very readable. By that I mean, can we read through the code and, at a glance, determine the rules it’s implementing? Can we see that Labor Day is accounted for? Can we tell that Saturday holidays are shifted to Friday? Not without mentally debugging it, line by line. The intent of the code (to meet the holiday calculation rules) is not revealed by reading the code. You’re left to figure it out yourself.

Some of the code loses readability by being too verbose. Take, for instance, the method used to determine if a particular date is a business date:

public bool IsBusinessDate(DateTime calendarDate)

bool isBusinessDate = false;

// Weekends and Holidays are not business days

if (IsWeekend(calendarDate) || IsHoliday(calendarDate))

isBusinessDate = false;

else

isBusinessDate = true;

return isBusinessDate;

That’s 11 lines of code (and one in-line comment) to express what could be expressed in one:

public bool IsBusinessDate(DateTime date)

return !IsWeekend(date) && !IsHoliday(date);

Not a weekend and not a holiday. Done. Smaller is not always better, but in this case I think it makes the code more precise and expressive while also minimizing the potential for a bugs to creep in.

Additionally, read through this block in the middle of the IsHoliday() method:

if (curDate.DayOfWeek == DayOfWeek.Monday)

if (curDate.Month == 1 && WhichMonday(curDate) == 3)

returnValue = true;

if (curDate.Month == 2 && WhichMonday(curDate) == 3)

returnValue = true;

if (curDate.Month == 9 && WhichMonday(curDate) == 1)

returnValue = true;

if (curDate.Month == 5 && LastMondayInMay(curDate) == true)

returnValue = true;

It is not immediately obvious what’s going on here. If you have the holidays memorized, you can tell that we’re checking for Martin Luther King, Jr. Day, Memorial Day, and a few other Monday holidays. But you have to stop and think about it, doing the mental calendar math to determine which holidays we’re dealing with. It would be better if the code expressed this explicitly.

Taking a step back

Before starting any refactoring, a decided to take a step back and think about how I would go about determining if a date was a holiday. The most straightforward way is to get a list of holidays, and then check my date against that list. That list of holidays must include the nine holidays listed in the rules above, adjusted for weekends if necessary.

I began the refactoring with that process in mind. To start with, I would need to generate the holiday list for the given year. So, I created a method to do so:

public IList<DateTime> HolidaysForYear(int year)

var holidayList = new List<DateTime>();

holidayList.Add(NewYearsDay(year));

holidayList.Add(MLKDay(year));

holidayList.Add(PresidentsDay(year));

holidayList.Add(MemorialDay(year));

holidayList.Add(IndependenceDay(year));

holidayList.Add(LaborDay(year));

holidayList.Add(ThanksgivingDay(year));

holidayList.Add(DayAfterThanksgivingDay(year));

holidayList.Add(ChristmasDay(year));

return holidayList;

After reading this method, there should be no doubt which holidays are accounted for. The intention of the method is explicit.

Since some of the holidays may fall on a Saturday or Sunday, they may need to be adjusted back a day (for Saturday) or forward a day (for Sunday). Hence:

private DateTime AdjustForWeekend(DateTime holiday)

DateTime adjustedHoliday = holiday;

switch (holiday.DayOfWeek)

case DayOfWeek.Saturday:

adjustedHoliday = holiday.AddDays(-1);

break;

case DayOfWeek.Sunday:

adjustedHoliday = holiday.AddDays(1);

break;

default:

break;

return adjustedHoliday;

We are explicitly implementing the “Holidays falling on Saturday will be observed on Friday and holidays falling on Sunday will be observed on Monday” rule. This allows us to calculate date-based holidays like this:

private DateTime NewYearsDay(int year)

var januaryFirst = new DateTime(year, 1, 1);

return AdjustForWeekend(januaryFirst);

New Year’s Day is January 1st, adjusted for weekends.

Next we have to deal with positional holidays, like the Labor Day (first Monday in September). I kept a couple of the helper methods that the original code had, only slightly altered:

private DateTime GetFirstDay(DateTime date, DayOfWeek dayOfWeek)

var dateToCheck = new DateTime(date.Year, date.Month, 1);

while (dateToCheck.DayOfWeek != dayOfWeek)

dateToCheck = dateToCheck.AddDays(1);

return dateToCheck;

private DateTime GetLastDay(DateTime date, DayOfWeek dayOfWeek)

var followingMonth = date.AddMonths(1);

var dateToCheck = new DateTime(followingMonth.Year, followingMonth.Month, 1).AddDays(-1);

while (dateToCheck.DayOfWeek != dayOfWeek)

dateToCheck = dateToCheck.AddDays(-1);

return dateToCheck;

Now that we can get the first or last DayOfWeek of any month, we can calculate all of the other holidays. Here’s Labor Day:

private DateTime LaborDay(int year)

var firstMondayInSeptember = GetFirstDay(new DateTime(year, 9, 1), DayOfWeek.Monday);

return firstMondayInSeptember;

In this case, I used a descriptive variable (firstMondayInSeptember) to add expressiveness, even though it isn’t necessary. It’s usefulness is more obvious when calculating Thanksgiving:

private DateTime ThanksgivingDay(int year)

var firstThursdayInNovember = GetFirstDay(new DateTime(year, 11, 1), DayOfWeek.Thursday);

var fourthThursdayInNovember = firstThursdayInNovember.AddDays(21);

return fourthThursdayInNovember;

Now that we have a list of holidays, we can check against that list to figure out if a given date is a holiday:

public bool IsHoliday(DateTime date)

var dateToCheckFor = new DateTime(date.Year, date.Month, date.Day);

return HolidaysForYear(date.Year).Contains(dateToCheckFor);

I kept much of the rest of the code the same, and I’ll leave it up to you to find other refactorings. But the end result, I hope, is Intention Revealing code. It not only meets the requirements, but does so in a way that explicitly reveals the requirements it was intended for. Incidentally, the final version has about 22% fewer lines of code (although reducing lines of code was not the goal).

Here is the final version after refactoring:

   1: namespace Your.Namespace.Here

   2: {

   3:     public class  DateService : IDateService

   4:     {

   5:         public DateProviderService()

   6:         {

   7:         }

8:

   9:         public bool IsBusinessDate(DateTime date)

  10:         {

  11:             return !IsWeekend(date) && !IsHoliday(date);

  12:         }

13:

  14:         public bool IsWeekend(DateTime date)

  15:         {

  16:             var dayOfWeek = date.DayOfWeek;

  17:             return dayOfWeek == DayOfWeek.Saturday || dayOfWeek == DayOfWeek.Sunday;

  18:         }

19:

  20:         public bool IsHoliday(DateTime date)

  21:         {

  22:             var dateToCheckFor = new DateTime(date.Year, date.Month, date.Day);

  23:             return HolidaysForYear(date.Year).Contains(dateToCheckFor);

  24:         }

25:

  26:         public DateTime CalculatePriorBusinessDate(DateTime fromDate, int numberOfBusinessDays)

  27:         {

  28:             if (numberOfBusinessDays < 0)

  29:             {

  30:                 string error = "Prior Business Days must be a positive number";

  31:                 throw new Exception(string.Format("reason : {0}", error));

  32:             }

  33:             return CalculateBusinessDate(fromDate, numberOfBusinessDays * -1);

  34:         }

35:

  36:         public DateTime CalculateSubsequentBusinessDate(DateTime fromDate, int numberOfBusinessDays)

  37:         {

  38:             if (numberOfBusinessDays < 0)

  39:             {

  40:                 string error = "Subsequent Business Days must be a positive number";

  41:                 throw new Exception(string.Format("reason : {0}", error));

  42:             }

  43:             return CalculateBusinessDate(fromDate, numberOfBusinessDays);

  44:         }

45:

  46:         public IList<DateTime> HolidaysForYear(int year)

  47:         {

  48:             var holidayList = new List<DateTime>();

49:

  50:             holidayList.Add(NewYearsDay(year));

  51:             holidayList.Add(MLKDay(year));

  52:             holidayList.Add(PresidentsDay(year));

  53:             holidayList.Add(MemorialDay(year));

  54:             holidayList.Add(IndependenceDay(year));

  55:             holidayList.Add(LaborDay(year));

  56:             holidayList.Add(ThanksgivingDay(year));

  57:             holidayList.Add(DayAfterThanksgivingDay(year));

  58:             holidayList.Add(ChristmasDay(year));

59:

  60:             return holidayList;

  61:         }

62:

  63:         private DateTime CalculateBusinessDate(DateTime fromDate, int numberOfDays)

  64:         {

  65:             int businessDayCount = 0;

  66:             int incrementValue = numberOfDays < 0 ? -1 : 1;

  67:             DateTime finalDate = fromDate;

68:

  69:             while (businessDayCount < Math.Abs(numberOfDays))

  70:             {

  71:                 finalDate = finalDate.AddDays(incrementValue);

  72:                 if (IsBusinessDate(finalDate))

  73:                 {

  74:                     businessDayCount++;

  75:                 }

  76:             }

  77:             return finalDate;

  78:         }

79:

  80:         private DateTime NewYearsDay(int year)

  81:         {

  82:             var januaryFirst = new DateTime(year, 1, 1);

  83:             return AdjustForWeekend(januaryFirst);

  84:         }

85:

  86:         private DateTime MLKDay(int year)

  87:         {

  88:             var firstMondayInJanuary = GetFirstDay(new DateTime(year, 1, 1), DayOfWeek.Monday);

  89:             var thirdMondayInJanuary = firstMondayInJanuary.AddDays(14);

  90:             return thirdMondayInJanuary;

  91:         }

92:

  93:         private DateTime PresidentsDay(int year)

  94:         {

  95:             var firstMondayInFebruary = GetFirstDay(new DateTime(year, 2, 1), DayOfWeek.Monday);

  96:             var thirdMondayInFebruary = firstMondayInFebruary.AddDays(14);

  97:             return thirdMondayInFebruary;

  98:         }

99:

 100:         private DateTime MemorialDay(int year)

 101:         {

 102:             var lastMondayInMay = GetLastDay(new DateTime(year, 5, 1), DayOfWeek.Monday);

 103:             return lastMondayInMay;

 104:         }

 105:

 106:         private DateTime IndependenceDay(int year)

 107:         {

 108:             var julyFourth = new DateTime(year, 7, 4);

 109:             return AdjustForWeekend(julyFourth);

 110:         }

 111:

 112:         private DateTime LaborDay(int year)

 113:         {

 114:             var firstMondayInSeptember = GetFirstDay(new DateTime(year, 9, 1), DayOfWeek.Monday);

 115:             return firstMondayInSeptember;

 116:         }

 117:

 118:         private DateTime ThanksgivingDay(int year)

 119:         {

 120:             var firstThursdayInNovember = GetFirstDay(new DateTime(year, 11, 1), DayOfWeek.Thursday);

 121:             var fourthThursdayInNovember = firstThursdayInNovember.AddDays(21);

 122:             return fourthThursdayInNovember;

 123:         }

 124:

 125:         private DateTime DayAfterThanksgivingDay(int year)

 126:         {

 127:             return ThanksgivingDay(year).AddDays(1);

 128:         }

 129:

 130:         private DateTime ChristmasDay(int year)

 131:         {

 132:             var decemberTwentyFifth = new DateTime(year, 12, 25);

 133:             return AdjustForWeekend(decemberTwentyFifth);

 134:         }

 135:

 136:         private DateTime AdjustForWeekend(DateTime holiday)

 137:         {

 138:             DateTime adjustedHoliday = holiday;

 139:

 140:             switch (holiday.DayOfWeek)

 141:             {

 142:                 case DayOfWeek.Saturday:

 143:                     adjustedHoliday = holiday.AddDays(-1);

 144:                     break;

 145:

 146:                 case DayOfWeek.Sunday:

 147:                     adjustedHoliday = holiday.AddDays(1);

 148:                     break;

 149:

 150:                 default:

 151:                     break;

 152:             }

 153:

 154:             return adjustedHoliday;

 155:         }

 156:

 157:         private DateTime GetFirstDay(DateTime date, DayOfWeek dayOfWeek)

 158:         {

 159:             var dateToCheck = new DateTime(date.Year, date.Month, 1);

 160:             while (dateToCheck.DayOfWeek != dayOfWeek)

 161:             {

 162:                 dateToCheck = dateToCheck.AddDays(1);

 163:             }

 164:             return dateToCheck;

 165:         }

 166:

 167:         private DateTime GetLastDay(DateTime date, DayOfWeek dayOfWeek)

 168:         {

 169:             var followingMonth = date.AddMonths(1);

 170:             var dateToCheck = new DateTime(followingMonth.Year, followingMonth.Month, 1).AddDays(-1);

 171:

 172:             while (dateToCheck.DayOfWeek != dayOfWeek)

 173:             {

 174:                 dateToCheck = dateToCheck.AddDays(-1);

 175:             }

 176:             return dateToCheck;

 177:         }

 178:     }

 179: }

The domain object that does everything

noreply@blogger.com (Eric King) — Thu, 21 May 2009 00:10:00 +0000

Continuing with my open ended series of posts whereby I conduct a refactoring experiment with BlogEngine.NET …

In my previous post ( Better readability using List.ForEach() and lambda expressions ) I refactored the newly created Catalog class and was left with some method calls that looked like this:

Post.PublishedPosts.ForEach(post => post.AddToCatalog());

The method for accessing the list of posts resides in the Post class itself, making the data access syntax somewhat similar to how it’s done with the ActiveRecord pattern or CSLA.

I don’t particularly like this structure, because it mixes what I consider to be two different concerns: domain (entity) logic and data persistence. It gives the Post class at least two distinct reasons to change, violating the Single Responsibility Principle and making the class probably a little more complex than it could be.

So, I decided to dive into the Post.cs file and see what I could do to simplify the class and remove some of the concerns that don’t fit directly in the domain object. What exactly is in the Post class? What does it do? After a quick once-through, I could see that the Post class:

Has properties that define the “Post” entity, like Title, Author, Content, etc.
Has event handlers that fire when posts are added, removed, rated, etc.
Manages an in-memory list of “Post” entities
Coordinates persistence to the data store by using the BlogService class
Formats its own relative, absolute, trackback, and permalink URIs by accessing the Utils and BlogSettings classes
Sends its own emails by calling out to the Utils class

There’s a lot going on in there. Personally, I think the domain object / entity class only needs to be concerned with the first two items in the list, and it should delegate out the rest of the stuff.

For the persistence, what I would prefer to see is something more like the Repository pattern used in Domain Driven Design. With a repository, all of the persistence is routed through a single class that acts “like an in-memory domain object collection.” Which, coincidentally, is exactly what’s stuffed inside the Post class. I just need to let it out.

In our case, the Post repository would be a class called Posts, physically and logically separated from the domain object’s Post class. We would end up with something that looks like this:

Posts.Published.ForEach(post => post.AddToCatalog());

From a syntax perspective, there’s only a subtle difference, but it’s an important one. We’re now treating the collection of Posts as a first-class object. And, by separating the persistence concerns out of the Post.cs class, it becomes much simpler and easier to maintain. As does the repository (Posts.cs) itself.

Persistence, however, isn’t the only external concern that needs to be pulled out. The URI generation is now in a class called RoutingAgent, which is also where I placed former Utils methods that calculate the RelativeWebRoot and AbsoluteWebRoot and such. The email logic is in the MailAgent class, as an extension method:

public static void SendNotifications(this Comment comment, Post post)

In the end, the Post.cs class is greatly simplified, and the post entity is no longer tightly coupled with non-post concerns like System.Net.Mail, BlogEngine.Core.Providers, System.Globalization, etc.

Next I’ll have to do the same type of refactoring with the other domain objects (Page, Comment, etc.).

Book Review: Dreaming In Code

noreply@blogger.com (Eric King) — Wed, 13 May 2009 16:38:00 +0000

Dreaming In Code: Two Dozen Programmers, Three Years, 4,732 Bugs, And One Quest For Transcendent Software

I found Dreaming In Code to be a fascinating book. On the surface it’s a narrative of a software development project, with some interesting industry history sprinkled throughout for context. But by telling it’s story, author Scott Rosenberg reveals two underlying truths about software development: producing quality, useful, non-trivial software applications is hard. And no team, no matter how good the members are, is immune to the inevitable setbacks and pitfalls.

Rosenberg, cofounder of the news and entertainment site Salon.com, does a great job detailing much of the early development of the Chandler Project, a “Note-to-Self Organizer”. The brainchild of Mitch Kapor (co-founder of Lotus Development Corp.), Chandler was intended to be the free, flexible, useable, everyman’s replacement for the expensive, corporate, stiff, hard to use Microsoft Outlook as a personal organization and communication tool.

“Chandler is an open source Note-to-Self Organizer. It features calendaring, task and note management and consists of a desktop application, web application and a free sharing and back-up service called Chandler Hub.
Our goal is to serve the way people actually work, independently and together, particularly in small groups, a market segment we believe is underserved. Our belief is that personal and collaborative information work is by nature iterative and that the existing binary Done/Not-Done, Read/Unread, Flagged/Unflagged paradigm in productivity software poorly accommodates the reality of how people work.”

Dreaming In Code is largely the story of how the grand vision of the birth of a new paradigm in personal organization software was slowly brought down to earth by the realities every programmer team faces, despite being helmed by a successful software visionary and staffed by some of the best and brightest in the industry. Faced with a lack of consistent direction, personality conflicts, time constraints, and sometimes simply biting off more than they could chew, the team struggled to find the success they were looking for.

Throughout the book, Rosenberg deftly helps the reader understand the motivation and principles that drove the team to try and create something new and different. To them, it wasn’t just a product, it was the beginning of a movement. But, there was no escaping the fact that it was also a software engineering project, lofty ambitions and altruistic motivations notwithstanding. We, through the author, are there in the meetings and celebrations, the good times and the frustrating times, riding the roller coaster along with everybody else.

Unfortunately, the book ends too soon. Rosenberg spends three years intimately involved with the project, but has to leave to publish it before the product is even close to being shipped. As a matter of fact, as the book comes to a close, we don’t even know if Chandler 1.0 ever shipped at all (it did). From the author’s blog:

It’s been close to six years since Mitch Kapor first announced plans for Chandler, and the application today is quite different from what was envisioned then. But it does fulfill at least a portion of the ambitious agenda Kapor set: It’s fully cross-platform, and, from the user side, it takes a very flexible approach to data. The program was once positioned as a calendar with email and task capabilities, and it’s still got those features, but it’s now presented as a notebook program — it’s “The Note-To-Self Organizer.” You store information free-form and then can organize it according to now/later/done triaging, turn items into tasks and schedule them on the calendar, group data in multiple collections, and share it across the web via the Hub server. I’m looking forward to experimenting more with it.

Aside from the missing end to the story, which can be found online anyway, the book is a great read.

The book jacket says that Dreaming In Code is “Not just for technophiles but for anyone captivated by the drama of invention.” I don’t think anybody who’s not at least somewhat related to software project management would find much interest in it. For those of us who are, though, it’s highly recommended.

Using List.ForEach() and lambda expressions

noreply@blogger.com (Eric King) — Fri, 08 May 2009 04:30:00 +0000

In my previous post, I refactored a small bit of the BuildCatalog() method, removing the need for the Catalog to know how to filter out the published posts and pages, and the approved comments.

What we were left with was a pretty simple method, but I think it could be made even more readable with a few tweaks. Here’s the code as it is after my changes:

private static void BuildCatalog()

{

OnIndexBuilding();

bool commentsEnabled = BlogSettings.Instance.EnableCommentSearch;

lock (_SyncRoot)

{

_Catalog.Clear();

foreach (Post post in Post.PublishedPosts)

{

AddItem(post);

if (commentsEnabled)

{

foreach (Comment comment in post.ApprovedComments)

{

AddItem(comment);

}

}

}

foreach (Page page in Page.PublishedPages)

{

AddItem(page);

}

}

OnIndexBuild();

}

There are a three foreach() blocks working on List<> objects, and within each block there’s a single line of code. That kind of code is just begging to be made a bit more elegant.

The .NET Framework 2.0 added the List.ForEach() method, which allowed for something like:

post.ApprovedComments.ForEach(delegate(Comment comment)

{

AddItem(comment);

}

Using a delegate, this syntax isn’t substantially better nor easier to read. However, toss in a lambda expression instead (introduced by .NET Framework 3.0), and ForEach() suddenly becomes juicily delicious:

post.ApprovedComments.ForEach(comment => AddItem(comment));

Yummy. All that blocky wordiness condensed to a simple, readable, one-line statement. Once we sprinkle those into our BuildCatalog() method, we may end up with something like:

private static void BuildCatalog()

{

OnIndexBuilding();

lock (_SyncRoot)

{

_Catalog.Clear();

if (BlogSettings.Instance.EnableCommentSearch)

{

Post.PublishedPosts.ForEach(post => AddPostAndComments(post));

}

else

{

Post.PublishedPosts.ForEach(post => AddItem(post));

}

Page.PublishedPages.ForEach(page => AddItem(page));

}

OnIndexBuild();

}

Much cleaner code, I think. My final version of the Catalog class, after extracting it from the Search.cs file and adding a few more refactorings (like an extension method or two), looks like this:

public static class Catalog

{

private static List<Entry> entries = new List<Entry>();

private readonly static object syncRoot = new object();

internal static List<Entry> Entries

{

get { return entries; }

}

internal static void AddItem(IPublishable item)

{

item.AddToCatalog();

}

internal static void Build()

{

OnIndexBuilding();

lock (syncRoot)

{

entries.Clear();

Page.PublishedPages.ForEach(page => page.AddToCatalog());

if (BlogSettings.Instance.EnableCommentSearch)

{

Post.PublishedPosts.ForEach(post => post.AddSelfAndCommentsToCatalog());

}

else

{

Post.PublishedPosts.ForEach(post => post.AddToCatalog());

}

}        

OnIndexBuilt();

}

private static void AddSelfAndCommentsToCatalog(this Post post)

{

post.AddToCatalog();

post.ApprovedComments.ForEach(c => c.AddToCatalog());

}

private static void AddToCatalog(this IPublishable item)

{

var entry = new Entry

{

Item = item,

Title = TextAgent.CleanContent(item.Title, false),

Content = HttpUtility.HtmlDecode(TextAgent.CleanContent(item.Content, true))

};

if (item is Comment)

{

entry.Content += HttpUtility.HtmlDecode(TextAgent.CleanContent(item.Author, false));

}

entries.Add(entry);

}

public static event EventHandler<EventArgs> IndexBuilding;

private static void OnIndexBuilding()

{

if (IndexBuilding != null)

{

IndexBuilding(null, EventArgs.Empty);

}

}

public static event EventHandler<EventArgs> IndexBuilt;

private static void OnIndexBuilt()

{

if (IndexBuilt != null)

{

IndexBuilt(null, EventArgs.Empty);

}

}

}

My little baby’s all grown up

noreply@blogger.com (Eric King) — Tue, 05 May 2009 06:13:00 +0000

In my previous post I began refactoring the BlogEngine.NET Search.cs file, specifically a portion of the “catalog” functionality. I’m going to continue my refactoring here …

But first, a little context. It seems that the searching algorithm (a method called BuildResultSet() ) works on “entries” in a collection called “catalog”, returning a set of “results”. An Entry is a struct defined right in the Search.cs file:

/// <summary>

/// A search optimized post object cleansed from HTML and stop words.

/// </summary>

internal struct Entry

{

/// <summary>The post object reference</summary>

internal IPublishable Item;

/// <summary>The title of the post cleansed for stop words</summary>

internal string Title;

/// <summary>The content of the post cleansed for stop words and HTML</summary>

internal string Content;

}

A Result is actually a completely separate class, contained also in the Search.cs file:

/// <summary>

/// A result is a search result which contains a post and its ranking.

/// </summary>

internal class Result : IComparable<Result>

{

/// <summary>

/// The rank of the post based on the search term. The higher the rank, the higher the post is in the result set.

/// </summary>

internal int Rank;

/// <summary>

/// The post of the result.

/// </summary>

internal IPublishable Item;

/// <summary>

/// Compares the current object with another object of the same type.

/// </summary>

/// <param name="other">An object to compare with this object.</param>

/// <returns>

/// A 32-bit signed integer that indicates the relative order of the objects being compared. The return value 

/// has the following meanings: Value Meaning Less than zero This object is less than the other parameter.Zero 

/// This object is equal to other. Greater than zero This object is greater than other.

/// </returns>

public int CompareTo(Result other)

{

return other.Rank.CompareTo(Rank);

}

public override int GetHashCode()

{

return Item.Id.GetHashCode();

}

}

Catalog, meanwhile, is defined as a local variable:

private static Collection<Entry> _Catalog = new Collection<Entry>();

Each of these items have a few methods set aside for them, such as “BuildCatalog()”, “AddItem()”, “CleanContent()”, and so forth. These pieces of code are all folded up and hidden away within regions in the Search.cs file.

The searching itself is done in a few methods, primarily BuildResultSet():

/// <summary>

/// Builds the results set and ranks it.

/// </summary>

private static List<Result> BuildResultSet(string searchTerm, bool includeComments)

{

List<Result> results = new List<Result>();

string term = CleanContent(searchTerm.ToLowerInvariant().Trim(), false);

string[] terms = term.Split(new char[] { ' ' }, StringSplitOptions.RemoveEmptyEntries);

string regex = string.Format(System.Globalization.CultureInfo.InvariantCulture, "({0})", string.Join("|", terms));

foreach (Entry entry in _Catalog)

{

Result result = new Result();

if (!(entry.Item is Comment))

{

int titleMatches = Regex.Matches(entry.Title, regex).Count;

result.Rank = titleMatches * 20;

int postMatches = Regex.Matches(entry.Content, regex).Count;

result.Rank += postMatches;

int descriptionMatches = Regex.Matches(entry.Item.Description, regex).Count;

result.Rank += descriptionMatches * 2;

}

else if (includeComments)

{

int commentMatches = Regex.Matches(entry.Content + entry.Title, regex).Count;

result.Rank += commentMatches;

}

if (result.Rank > 0)

{

result.Item = entry.Item;

results.Add(result);

}

}

results.Sort();

return results;

}

So, where am I going with this? I’m glad you asked. :-)

It seems to me that this one file, Search.cs, is trying to do too many complex things. It’s defining several entities (Entry, Result, Catalog), managing them (BuildCatalog(), BuildResultSet()), searching them (APMLMatches(), Hits()), manipulating them (CleanContent(), FindRelatedItems(), ResultToPost()), and handling events (Post_Saved(), Post_CommentAdded(), OnSearching()). It’s probable that the search functionality started out pretty simple, and grew more complex over time.

When that happens to our code, we should practice a little “ruthless refactoring” and extract these groups of functionality into their own classes where appropriate. In other words, when your baby methods grow up, make them move out and get their own home. In this way, we can keep the “Search” class concerned with searching, not maintaining the content catalog or sanitizing the result’s text. I don’t think enough of that was done here, so I’m going to do it.

The first thing I did when I opened up this file (even before what I did in the previous post), was extract the “catalog”, and give it some freedom. My new Catalog.cs, all grown up now (and with a few more refactorings which I’ll explain later), looks like this:

public static class Catalog

{

private static List<Entry> entries = new List<Entry>();

private readonly static object syncRoot = new object();

internal static List<Entry> Entries

{

get { return entries; }

}

internal static void AddItem(IPublishable item)

{

item.AddToCatalog();

}

internal static void Build()

{

OnIndexBuilding();

lock (syncRoot)

{

entries.Clear();

Page.PublishedPages.ForEach(page => page.AddToCatalog());

bool commentSearchEnabled = BlogSettings.Instance.EnableCommentSearch;

if (commentSearchEnabled)

{

Post.PublishedPosts.ForEach(post => post.AddSelfAndCommentsToCatalog());

}

else

{

Post.PublishedPosts.ForEach(post => post.AddToCatalog());

}

}

OnIndexBuilt();

}

private static void AddSelfAndCommentsToCatalog(this Post post)

{

post.AddToCatalog();

post.ApprovedComments.ForEach(c => c.AddToCatalog());

}

private static void AddToCatalog(this IPublishable item)

{

var entry = new Entry

{

Item = item,

Title = TextAgent.CleanContent(item.Title, false),

Content = HttpUtility.HtmlDecode(TextAgent.CleanContent(item.Content, true))

};

if (item is Comment)

{

entry.Content += HttpUtility.HtmlDecode(TextAgent.CleanContent(item.Author, false));

}

entries.Add(entry);

}

public static event EventHandler<EventArgs> IndexBuilding;

private static void OnIndexBuilding()

{

if (IndexBuilding != null)

{

IndexBuilding(null, EventArgs.Empty);

}

}

public static event EventHandler<EventArgs> IndexBuilt;

private static void OnIndexBuilt()

{

if (IndexBuilt != null)

{

IndexBuilt(null, EventArgs.Empty);

}

}

}

Similarly, I’ll do the same type of extraction to other pieces of Search.cs, leaving each of the individual pieces simpler, more single-purpose, and ultimately (I hope) easier to understand and manipulate.

Coming up next, I take advantage of some .NET 3+ functionality to further refine the code.

Put functionality where it belongs

noreply@blogger.com (Eric King) — Sat, 02 May 2009 22:04:00 +0000

In one of my recent BlogEngine.Net Experiment refactoring sessions, I found myself working on the BlogEngine.Core Search.cs file. Very quickly I noticed that the search functionality works on a “catalog” object, which is a local Collection<Post> type variable. Various methods work on this collection, “building" it, adding to it, and so forth.

The BuildCatalog() method looks like this:

private static void BuildCatalog()

{

OnIndexBuilding();

lock (_SyncRoot)

{

_Catalog.Clear();

foreach (Post post in Post.Posts)

{

if (!post.IsPublished)

continue;

AddItem(post);

if (BlogSettings.Instance.EnableCommentSearch)

{

foreach (Comment comment in post.Comments)

{

if (comment.IsApproved)

AddItem(comment);

}

}

}

foreach (Page page in Page.Pages)

{

if (page.IsPublished)

AddItem(page);

}

}

OnIndexBuild();

}

Notice how, in the first ForEach, all of the posts are requested (Post.Posts), but we only want to work on the published ones. So, we open up and inspect each post to see if it’s published before continuing.

We then do the same thing for Comments, getting them all but only working with the approved ones. And we do it yet again with Pages, getting them all when we only want the published ones.

There’s obviously some extra work going on here, but how should we refactor it?

One of the problems with this code is that the Catalog needs to know too much about the internals of a Post, a Comment, and a Page to do its work. The Catalog shouldn’t need to know that a Post and a Page will have an IsPublished property, nor that a Comment will have an IsApproved property. (See the definition of the Inappropriate Intimacy code smell.) It should simply be able to ask for published posts, approved comments, and published pages from the appropriate provider.

But who can the Catalog ask? Neither the Post class nor the Page class can provide the answer, so the Catalog does the best it can. The solution, then, is to fix the Post and Page classes so that they can provide the Published and Approved content themselves.

Once done, the BuildCatalog() method will look more like this:

private static void BuildCatalog()

{

OnIndexBuilding();

bool commentsEnabled = BlogSettings.Instance.EnableCommentSearch;

lock (_SyncRoot)

{

_Catalog.Clear();

foreach (Post post in Post.PublishedPosts)

{

AddItem(post);

if (commentsEnabled)

{

foreach (Comment comment in post.ApprovedComments)

{

AddItem(comment);

}

}

}

foreach (Page page in Page.PublishedPages)

{

AddItem(page);

}

}

OnIndexBuild();

}

The BuildCatalog() method is simpler and more straightforward. It’s also decoupled from the internals of the Post, Comment, and Page classes, in the sense that it doesn’t need to know how to determine if a post or page is published, it just asks for them.

In the next couple of posts I’ll walk through a few more refactorings of the ‘catalog’ functionality.