Month: February 2010

I seem to be starting a series of posts on good advice gone bad.  KISS is a great piece of advice, Fail Early is another.  Like KISS, it’s advice that scales: it’s as appropriate to function design (don’t return spurious default values on failure) as it is to project management (find out that something’s gone wrong now, not in three months time).  The basic idea is the same: provide instant feedback that something is wrong.  Don’t let the problem grow.

On the other hand, there’s nothing in “Fail Early” that says that you need to completely fail.  I once was advising on a store-front application.  It took the prices and products from various third-party suppliers.  However, if there was anything wrong with the data, the whole feed would fail.

Now, it certainly “Failed Early”.  But it didn’t observe the spirit of the phrase.  For one thing, it didn’t actually tell anyone.  It waited for someone to notice that the prices were wrong on the live site.  It’s definitely feedback, but really the sort you want.  The worst of it, though, was the “all or nothing” approach to failure.  Now, sometimes you’ll make a decision to do it this way, but typically this will be because data is inconsistent if you don’t.  A price list is not one of those cases.  99% of prices could typically be processed completely successfully.

So, Fail Early.  But don’t Fail Catastrophically.

10. Because C# isn’t your first language.

9. Because your mate on the desk next to you isn’t going to be there for ever.

8. Because activity is obvious, purpose is not.

7. Because you need to take a break from talking jargon all the time.

6. Because it may not reduce the number of stupid phone calls you get, but at least it’ll shorten them when you tell them the URL where you’ve already answered the question.

5. Because it keeps you honest: if it’s hard to explain, it’s probably wrong.

4. Because you’re not going to remember how it works in five years time.

3. Because it makes it easier to spot holes in your use cases.

2. Because the internet isn’t full of source code reading savants.

1. Because one day, someone might thank you for it.

And yes, for the record, I have been writing documentation recently.

I’ve finally managed to get enough time to knock out a release of Solution Transform.  The original Silverlight transform code is unchanged, but there’s a lot of new features.  It’s now usable for quite a number of build tasks.  I’ve even actually written a documentation page on how to use it.  if feedback is positive, I’ll actually make a binary distribution of the tool.

Basically, it now allows you to script conversion to Silverlight, adding and removing of projects, rebasing of assemblies, renaming of projects, and merging and demerging of solutions.  When I next get to it, I’m planning on enabling parallel VS2010 and VS2008 work. 

A note about the source code repository, the Castle Project as a whole is currently moving to github, and Contrib will no longer be hosted directly by Castle.  I’ve moved Solution Transform already because it was actually pretty easy for me to do, having no history that was worth keeping.

I recently had occasion to use Boo’s macro feature in anger.  In particular, I wanted to build something like “with” in JavaScript.  Those who aren’t familiar with Boo’s macros might think this couldn’t be that hard.  I mean, there’s an example that does this right on the page, isn’t there?

Ironically, the example actually demonstrates the limitations of boo’s macros, rather than their power.  Let’s start with the requirement to prepend method names with an underscore.  It shouldn’t be too hard to make it use a dot just like VB, should it?  Well, no, an expression that began with a dot wouldn’t be syntactically valid.  So here we have the first major restriction: you can’t create new syntactic structures, you can only abuse the ones that are already there.

That isn’t what I wanted to do, however, I wanted JavaScript’s with statement.  I didn’t want to prepend anything to the method name, I just wanted to use the method name and have it resolve to the instance’s method.  Shouldn’t be too hard, just look up the instance’s type’s method names and rewrite the appropriate expressions.  Only you can’t do that: they’re called “syntactic” macros for a reason: there’s no semantic information, including type, available at this point.  You’ll note that this has a knock-on effect on the using macro.  The check that the subject of the macro implements IDisposable is at runtime.  In C#’, it’s at compile time.  Probably not the end of the world, but I think people would be surprised if “using (3) {}” compiled in C#.*

There are other ways to achieve the effect, you could push delegates into the execution scope, but supporting overloading would be hairy in the least.  You could do an import, but that will only work with static methods.  In general terms, the syntactic macros don’t give you enough unless you’re prepared to be really ugly and the static type system takes away flexibility you’d have had in a proper dynamic language like JavaScript, Python or Ruby.

Now, I’ve had some reservations about the conceptual value of macros anyway, and this has firmed up my opinions.  Macros are only useful if they’re relatively easy for the user to understand intuitively what they do.  It’s interesting to look at Binsor here.  For the most part it presents you with a view of the world that suggests the mapping from the DSL to Castle Windsor is simple.  However, once you start digging under the hood, it gets unpredictable.  To this day, I have no idea how to configure a facility; I’m using code ripped off the internet for each one.  I remember it took me a day to figure out how to set a config value on a component.  Ultimately, it’s a pretty big code base for something that can be 90% replaced with 5 lines in a blog post.  (Not 100% yet, though.  I’ll let you know when I’ve done that.  🙂 )

Obviously, all tools have advantages and disadvantages.  But with Boo, I’m just not sure it’s got an advantage over IronPython I care about.  I eventually ended up adopting pretty much the “with” code in the sample, because I don’t believe it can be usefully improved. 

Technorati Tags: Boo,Binsor,DSLs

Yeah, yeah, yeah, I know I shouldn’t create aggregate roots.  However, sometimes I just want to hack something together and I don’t particularly feel like wasting my time with stored procedures.  However, if you’ve got an old list and a new list and you need to sync up the changes to the database, the code to do this isn’t exactly obvious.  What’s worse, some of the error messages you get when you get it wrong are positively unhelpful.  My personal favourite is “Non-static method requires a target” (what on earth is NHibernate doing that generates that error?) but “a different object with the same identifier value was already associated with the session” when you called a method called session.Merge comes a close second.

Anyway, here’s the code.  Wrap it in a transaction if you care at all about performance.

void Synchronise<TValue>(IEnumerable<TValue> current, IEnumerable<TValue> desired)
{
    foreach (var value in current.Except(desired))
    {
        session.Delete(value);
    }
    foreach (var value in desired.Except(current)) {
        session.Save(value);
    }
    foreach (var value in desired.Intersect(current))
    {
        session.Merge(value);
    }
}

Note that I’m assuming that TValue implements Equals and GetHashCode correctly, which you should be doing anyway if you’re using NHibernate.

KISS (Keep It Simple, Stupid) is one of the single best and most general pieces of advice you can give a developer.  It seems that we’re genetically predisposed to overcomplicating things.  From the C programmer trying to come up with best way to twiddle bits to the ASP.NET programmer coming up with a caching strategy, we over-optimize all of the time.  We build solutions to problems that don’t exist and may never exist.  (The best example I saw of this was an exercise in internationalising a web application which had a problem domain that only applied to the UK.  Never has YAGNI been more appropriate.)

The problem is, many developers don’t really seem to understand the meaning of the phrase “Simple”.  Like design patterns, I’ve too often seen KISS quoted to justify frankly bad designs.

KISSing Clever

“Simple” doesn’t mean quite the same thing as “a trained monkey could do it”.  “Simple” is about expressing things in a direct fashion, which isn’t quite the same thing as being easy to understand.  Programming is a fundamentally logical profession, and some people don’t really handle logical entailment very well.  You will not be improving your code by expressing it in such a way that you try to accommodate them.  Equally, some developers aren’t really up to speed with modern techniques, such as dependency injection and ORMs.  If you thought that “simple” meant not using modern tools, you should probably be programming in COBOL (or C++, for that matter).

The objection that you often get when someone first encounters NHibernate or nServiceBus is that it all seems too complex.  Davy wrote a series of articles on how to write your own ORM.  Does that mean that NHibernate is overkill and you can junk it?  Well, consider this:  Davy is a project committer and cares deeply about its future.

The problem is, when you start with NHibernate, the requirement to override Equals and implement virtual methods seems like a royal waste of time.  It’s only when you understand the problems it’s trying to solve that you start to regard these requirements as being natural.  Now, I’m not here to re-open build versus buy yet again, I’m pointing out that “simple” is a function of your problem domain.  And your problem domain is nearly always larger than you think it is when you start a new project.

Make Complexity Explicit

Okay, I’ve finally managed to edge up to my point.  I’ve encountered a number of phenomenally complex systems over the years that were held together by pieces of string.  Each of these was designed that way in an incremental fashion.  A CSV export there, a URL rewrite rule, all slowly built up into a system that absolutely no-one understood.  The worst of it was the decisions were made with good intentions.  The desire for simplicity drove the design to purgatory.

The problem is, simplicity can’t be evaluated on a case by case basis, it has to be done holistically.  Some things are hard, and some things are complex.  Sometimes you can replace a hard problem with a simple one, but sometimes it’s essential complexity.  In these cases, it’s better to recognize that and make it explicit in the design than to try to shove it away.  When everyone does that, the complexity doesn’t disappear, it just becomes implicit in the interaction between your components.  Any solution that involves the words “side-effect” or “magic” isn’t simple, it’s just deceptively complex.  Keep it simple, but keep it smart as well.

Technorati Tags: KISS,YAGNI,Design Patterns