hero banner

Archive for April, 2009

C# Extension Methods To Get Enum DescriptionAttributes And Other Custom Attributes

Thursday, April 23rd, 2009

A quick code snippet.  These two extension methods (C# 3.0+) enables you to return custom attributes from types, both on a specific type and any data type.  They both return null if the attribute is not present.  

The first extension is useful for extending a type of your choice.  It’s especially useful when considering Enums and the DescriptionAttribute, or other enumeration attributes (especially custom attributes).  The usage examples below should make the use more obvious.

The second extension allows you to return an Attribute from ANY type.  Use with caution, but I find it interesting that it’s actually possible to write an extension method that works that way.

    public static class ElementExtensions
    {    

        public static T GetAttributeValue<T>(this SomeConcreteType val)
        {
            var attributes = val.GetType().GetField(val.ToString()).GetCustomAttributes(typeof(T), false);

            T response = default(T);
            if(attributes.Length > 0)
            {
                response = (T)attributes[0];
            }

            return response;
        }

        public static TReturnType GetAttributeValueFromType<TInstanceType, TReturnType>(this TInstanceType val)
        {
            var attributes = val.GetType().GetField(val.ToString()).GetCustomAttributes(typeof(TReturnType), false);

            TReturnType response = default(TReturnType);
            if(attributes.Length > 0)
            {
                response = (TReturnType)attributes[0];
            }

            return response;
        }       
    }   

Some usage examples….

    public enum RegexEnum
    {
        [RandomAttribute("^(([a-zA-Z]{1}[0-9]{3,4})|([a-zA-Z]{2}[0-9]{2,3})|[0-9]{4})$")]
        SomeEnumValue,
    }   

    public class RandomAttribute: Attribute
    {
        public string Expression { get; set; }

        public RandomAttribute(string expression)
        {
            Expression = expression;
        }
    }

    private static void Example()
    {
        // Both of these are equivalent
        foreach(var enumMember in Enum.GetValues(typeof(RegexEnum)))
        {
            var value = enumMember.GetAttributeValue();   
            var valueFromAnyType = enumMember.GetAttributeValueFromType<RegexEnum, RandomAttribute>();
        }       
    }

Some nice syntactic sugar for use with enumerations.

Installing certificates using WiX / Voltive (A Code Sample)

Wednesday, April 22nd, 2009

I’ve previously provided a code snippet illustrating how to use WiX (the “new” Windows Installer framework) to install certificates onto the target machine.

I’ve had some good feedback about the post, but also had a request for a working example (in order to illustrate how the code fragment is used in an Installer.wxs file).

I’ve cooked up a sample visual studio solution that installs a test certificate (generated using the MSDN makecert certificate example “makecert -sk XYZ -n “CN=XYZ Company” testXYZ.cer “).

You’ll probably need to re-path references to the WixIISExtension and WixUIExtension in relation to your development environment but hopefully this should help you.

The previous post is the third most accessed post in my blog (which probably speaks as much for the number of people that read this as it does it’s utility) so this should be useful to someone.

It’s worth noting that this example installs the junk certificate as a Root CA so you might want to change that or ensure you remove it once you’re done.

Download the Sample Solution

Using A Wiki To Replace Requirements And Produce Documentation For Your Agile Projects

Tuesday, April 7th, 2009

I Know It Sucks, But You Need Requirements To Work

There are two parts of software development that really suck. Traditional requirements analysis and documentation. This isn’t some silly joke, both practices are terribly antiquated and essentially useless, not least in an agile (read: rapidly changing) project.

However, one of the common misconceptions I often hear when working on agile projects is stakeholders not quite “getting it” and thinking that agile is the same thing as requirement-less development.

However you paint it, you need something that resembles requirements to write code with. Requirements needn’t be exhaustive, and in an agile environment are rarely ever final, but you need to know what you’re working on- the average user story isn’t going to cut it.  User stories are designed to start conversation between the developer and the stakeholder but you need to do something with the detail once you have it.

Make The Requirements As Accountable As You Are

You know what else sucks? The fact that most businesses don’t have any kind of document management strategy. Sure, you do, you’re a developer. You have source control (and if you don’t, go take care of that now), you’re accountable and auditable line by line, check-in by check-in. This same rigor rarely extends to other areas of businesses (though it should).

When all is said and done, if you’re maintaining a traditional requirements document for your project you’re probably already making a big mistake. Who owns the document? How do you track changes? How do you know people haven’t changed the requirements without a reasonable discussion? What happens when somebody accidentally deletes it?

Requirements documents are the “Excel Applications” of development. They’re unreliable, often so large that nobody will ever read them, and as such fundamentally useless. It’s a bit of a trick question really, monolithic requirements documents are about as “Write-Once-Read-Never” as most Perl code.

I Think We Have a Problem…

So lets recap. Requirements documents are evil and nobody reads them, but you need requirements to develop. Requirements documents aren’t auditable yet it’d really be a good idea if they were. Oh and documentation sucks.

You Need Wikimentation!

Wikimentation is a particularly amusing portmanteau but what you need is a wiki and if you do it right, you’ll never have to write documentation again.

In an agile project, the requirements are meant to evolve and change as you go, so they deserve to be stored in a format that naturally leans towards allowing the users to do just that.

There’s also an immediate bonus to either you or your business analysts in the way requirements are captured as a traditional requirements capturing exercise is eschewed in favour of documenting requirements as they become relevant. This is a very natural way of working and allows you to prototype or stub out components until you need to delve into detail (in fact, doing this is very much the SCRUM way).

When I approach a new project I like to keep a few things in mind, I’ll call them the Holy Trinity of software maintainability…

The Holy Trinity Of Software Maintainability

  • Readable Code
  • Good Developer Documentation
  • Source Control

So how will a wiki help you get there?
I’d argue that after the implementation of a set of requirements, the requirement and it’s details have effectively been superseded by the precedent set in the code.

Those requirements you coded to, after implementation are useless. If the code doesn’t adhere to the requirement the code is buggy, and your bug tracking system should contain information explaining why.

If the code is correct, the requirements would be classified as obsolete. Keeping them around only serves the purpose of misleading anyone who attempts to read the requirements to establish the coded behaviour of an application.

So what we do is we maintain the list of requirements in a wiki in a slightly less formal manner. This is hypertext remember, big long lists of stuff are so 1990. Use links and divide the content into requirements for logical components, leaving a well maintained index on the project homepage in the wiki.

Now as features are completed instead of the requirements eventually rotting away into irrelevance, they can be replaced by a simple developer commentary of the implementation. As you follow this pattern, your requirements will develop into a solid set of searchable developer documentation at the same rate as your project progresses.

Constructing Your Own Evolving Requirements Wiki

There are plenty of FOSS and OSS Wiki platforms out there. I have a personal preference for ScrewTurn Wiki on Windows and you can be up and running in literally under 5 minutes (web server not even required).

A few simple guidelines

  • Ensure that the home page of your wiki clearly links to the discrete sub projects or components you’re developing
  • It’s encouraged to create wiki links for content that doesn’t exist but needs elaborating on by yourself or your team, to serve as a visual reminder of what is left to do
  • Create a standard template for a project and component wiki page
  • Populate each of your component wiki pages with the top level requirements for that component, along with “pre-links” to any sub-components of specific note or percieved complexity
  • Encourage your developers to document as they write
  • Don’t duplicate code comments or huge chunks of code in the wiki – that’s what clean and readable code is for
  • Do encourage the posting of examples for reusable or common components – share individual developer knowledge

The wonderful thing about using a wiki is that it breeds accountability. Modifications are logged and audited; you can always see the history of any given page, from requirements to documentation.

A wiki will provide you with a sound and adaptable framework for producing project documentation that evolves with your project. Used in conjunction with a good bug tracking system, a good version control system and some good developers, you’ll have a good chance at edging closer to that holy grail of maintainable well documented code at low cost.

Zero Friction Documentation

Your developers won’t resent a little bit of writing as they finish off logical units of work, and it could be even encourage to keep a “scratchpad” of information on the wiki as opposed to paper-notebooks. It’s also good to remember that you can always generate a traditional requirements document from the content stored in the wiki if an occasion calls for it.

I’ve had a lot of success implementing these ideas in past projects (both agile and none agile) and I’d certainly recommend it.

Why We Need Male Dominated Space Marine Action Games

Tuesday, April 7th, 2009

This is a round about response to both Leigh Alexander’s response to Heather Chaplin’s GDC rant session.  It’s worth noting that I wasn’t at GDC and that all my information is second hand, and as such, susceptible to Chinese whispers-style misinformation.  To quote Leigh’s post (as a good source of a direct quote)

‘She argued that medium’s age is not the correct source of blame for the often insultingly juvenile nature of games, the tiresome prevalence of space marines, bikini girls and typified young male power fantasies. Her point: Games aren’t adolescent. Game developers are a bunch of, in her words, "fucking adolescents."’

This is really not a response to Leigh’s post at all, but more to the original subject that it made me aware of. 

I always feel a bit defensive when people imply that the only video games that ever get produced are space marine staring male power-fantasies. 

Just as a case point, lets take a look at the top selling games of last year (via a quick Google search)

Wii Play
Mario Kart Wii
Wii Fit
Super Smash Bros Brawl
Grand Theft Auto IV
Call of Duty: World at War
Gears Of War 2
New Super Mario Bros
Madden NFL 09

It’s difficult to claim that all of those titles fit into that narrow criteria.

There’s often talk of cinema reaching a comparative maturity with the release of Citizen Kane, and The Beatles representing the maturity of pop music by a similar timeframe in their respective mediums development.

I really don’t think that the respective age of the medium is a safe measure to judge it’s maturity.  By the time of Citizen Kane and the Beatles arrived in their respective mediums the supporting technology had plateaued to a degree that allowed for artists to have unencumbered technical freedom in comparison to the respective "technical freedom" that game designers have now.

There are a lot of critics that underplay the difficulty of perfectly nailing both concept and execution of a game.  It’s difficult, stuff, even more difficult to make the game work well, be playable and be great.  If you manage artistic integrity and ingenuity on top of that you’ve managed something exceptional. 

It’s no surprise that some of the most celebrated titles in video gaming are often technically flawed "classics" that get lauded for being "near misses".  Taking risks on titles is difficult and expensive on top of the desire to be artistically vibrant.

I certainly don’t think Citizen Kane would have had the budget and resource to be "great" if the camera men were still learning how to use cameras and I really think that we’ve got a way to go before we can expect every game made to be a high concept piece. 

Even after the technology reaches this point (as it has in the film industry) there’ll still be more summer action films / games made than artistic victories.

It’s also worth nothing that in this constant strive for something else, it’s easy to loose the purity and fun of more "pure" game play experiences, including male power fantasies and computerised D&D implementations.  Some people find game mechanics fun, to some people that is the point and it always feels that some critics always call so loudly for something different that they miss some of the point of what we already have.

The artistic indie film vision of influential games is a laudable one, but without the Gear of War’s there just isn’t the ecosystem to support them.  Much like when I watch films, I don’t always want to watch Capote or Chinatown.  Sometimes I want to watch Die Hard, and sometimes I want to watch Star Wars.  And sometimes I’d quite like to watch Twelve Monkeys or Being John Malkovich, but without Star Wars, the framework to support those often loss-leading productions just wouldn’t exist.

I don’t pretend to play at “legitimate game criticism” however I certainly follow the area with more than a casual interest and I’m often very surprised at how the desire for strong artistic games in the “niche of a niche” press seems to forgo the need for any other kind of game. 

The last thing I’d want is for the games press to take a Pitchfork media style pretentious view of the world, reducing anything that isn’t trendy or progressive to dirt.  There’s tonnes of very good games writing out there that I very much enjoy reading and I really hope that people allow at least some games to still be “just games” alongside the more “worthwhile” and “deep” experiences available.

David Develops…

Monday, April 6th, 2009

A little bit of site administration…

Anyone who writes on the internet will happily tell you that the best way to keep your readers happy is to carve out a niche and devote your time to well researched detailed content.

I’ve always treated davidwhitney.co.uk as a traditional “home page”. It’s my blank canvas, and I intend to keep it that way. However, a lot of my content is straying deeper into more technical topics that don’t flow with the rest of the content.

In an attempt to tighten the focus of my writing, I’ve registered the URL http://daviddevelops.co.uk (following the tried and tested practice of terrible “developer name in title” blogs!).

The actual content of the two sites is the same, they run off the same database, the same tables. David Develops is a subset of the content available on davidwhitney.co.uk. Siphoning off the develop-oriented content also allows me to use an alternate site layout more applicable to technical content / posting source code. No more red-on-black source code samples.

If you are only interested in the technical content available I’d recommend you subscribe to the feed available on that site rather than the main davidwhitney.co.uk feed, because you don’t want to end up looking at pictures of cats.

Due to the shared database (“David Develops” is a quickly carved up version of WordPress that grabs specifically catagorised posts) any comments you post here will be visable on the other site, and vice versa.

I expect that by refocusing I’ll be able to cover more topics in depth in the future, on both sides of the fence, guilt free.