I got a message from a friend who was struggling to do an integration piece with the Magento eCommerce Platform using the SOAP endpoint available at http://yourserver.co.uk/api/v2_soap?wsdl.

He brought an interesting problem to me, namely that the WCF svcutil executable (and built in Visual Studio 2008) was failing to generate any proxy code when supplied with a seemingly valid wsdl.

I did a quick test and managed to instantly reproduce the error.

Weirder still, when using the “old” .Net 2.0 add web reference method rather than the .Net 3.0+ “Add Service Reference”, the framework managed to create a non-WCF reference just fine.

Dropping down to the command line I saw some unusual messages being displayed by svcutil.exe:

c:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin>SvcUtil.exe http://yourserver.co.uk/api/v2_soap?wsdl
Attempting to download metadata from ‘http://yourserver.co.uk/api/v2_soap?wsdl’ using WS-Metadata Exchange or DISCO.

(Lots of error messages here…)

Error: Cannot import wsdl:portType
Detail: An exception was thrown while running a WSDL import extension: System.Se
rviceModel.Description.XmlSerializerMessageContractImporter
Error: The ‘ ‘ character, hexadecimal value 0×20, cannot be included in a name.
Parameter name: name
XPath to Error Source: //wsdl:definitions[@targetNamespace='urn:Magento']/wsdl:p
ortType[@name='Mage_Api_Model_Server_V2_HandlerPortType']

Error: Cannot import wsdl:binding
Detail: There was an error importing a wsdl:portType that the wsdl:binding is de
pendent on.
XPath to wsdl:portType: //wsdl:definitions[@targetNamespace='urn:Magento']/wsdl:
portType[@name='Mage_Api_Model_Server_V2_HandlerPortType']
XPath to Error Source: //wsdl:definitions[@targetNamespace='urn:Magento']/wsdl:b
inding[@name='Mage_Api_Model_Server_V2_HandlerBinding']

Error: Cannot import wsdl:port
Detail: There was an error importing a wsdl:binding that the wsdl:port is depend
ent on.
XPath to wsdl:binding: //wsdl:definitions[@targetNamespace='urn:Magento']/wsdl:b
inding[@name='Mage_Api_Model_Server_V2_HandlerBinding']
XPath to Error Source: //wsdl:definitions[@targetNamespace='urn:Magento']/wsdl:s
ervice[@name='MagentoService']/wsdl:port[@name='Mage_Api_Model_Server_V2_Handler
Port']

Generating files…
Warning: No code was generated.
If you were trying to generate a client, this could be because the metadata docu
ments did not contain any valid contracts or services
or because all contracts/services were discovered to exist in /reference assembl
ies. Verify that you passed all the metadata documents to the tool.

Warning: If you would like to generate data contracts from schemas make sure to
use the /dataContractOnly option.

c:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin>

So I did a little digging through the WSDL and found an undocumented bug in Magneto’s schema.

First I saved a local copy of the WSDL and used visual studio to reformat the document into some sort of readable state, then I had to make a few corrections to the WSDL to allow SvcUtil to correctly parse the malformed document.

Change 1:  Replace a badly encoded apostrophe – I removed the “’s” from the following operation definition…

<operation name="customerGroupList">
<documentation>Retrieve customer’s groups</documentation>
<input message="typens:customerGroupListRequest"/>
<output message="typens:customerGroupListResponse"/>
</operation>

Change 2: Replace a trailing space in an operation name

<message name="catalogProductGetSpecialPriceRequest">
  <part name="sessionId" type="xsd:string"></part>
  <part name="product" type="xsd:string"></part>
  <part name="storeView " type="xsd:string"></part>
</message>

If you look carefully at the above message definition, you’ll notice that name=”storeView “ contains a space, making the wsdl invalid.  Remove the space so it reads “storeView”.

With these two errors corrected, SvcUtil had no problem generating an appropriate WCF proxy from the corrected wsdl file.

Magneto will hopefully fix this error in the WSDL, but until this time, it’s probably quite safe to follow these steps to generate your own proxy.

To reproduce:

• Go to http://yourserver.co.uk/api/v2_soap?wsdl and save the contents of your file to the local disk (c:\test\main.wsdl)
• Open the file in visual studio, and reformat the document for readability (CTRL+K, CTRL+D).
• Remove the apostrophe from the documentation tag for the customerGroupList operation.
• Remove the space after the name=”storeView “ in the catalogProductGetSpecialPriceRequest message definition.
• Open a command prompt and enter
• c:\test>c:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin\svcutil.exe main.wsdl
• SvcUtil will produce two files, Magento.cs (your WCF proxy) and output.config, your endpoint configuration.

With the popularity of service oriented architectures and other buzz phrases related to software as service, good API design has become a significant selling point for any software platform in the past 5-10 years.  People make purchasing decisions based on how easy it is to interoperate with your applications and code and as such the number of client / public facing APIs attached to software has skyrocketed.  I’d like to believe the days of dropping strategic text files in directories to trigger some action or another in an application are behind us.

In this article I’m going to talk about the following things

• Why you should choose your method names carefully, and what to call
• Why pretending to be a data access layer is a terrible thing for an API to do
• Talk about the dangers of leaky abstractions in an API
• Explain the benefits of creating a data contract between you and the calling code
• Explain why it’s vital to support standards
• Make sure that your users can retrieve values they’re going to want to modify
• Suggest supplying compiled libraries alongside your API documentation
• Explain why it’s important to keep your API implementation clean
• Talk about the benefits of dogfooding your API
• Consider supporting atomic operations including rollbacks on failure
• Discuss bulk operations
• Try and convince you that both logging and security should be first class citizens
• Beg you to maintain integration tests and most of all to keep it simple!

Your API Sucks

You’ve probably used an API and there’s a good chance you’ve had to write one.  This probably won’t surprise you; most APIs suck.  They’re horrible to use and built around illogical leaky abstractions that leave you flicking through huge wads of documentation just to make the most rudimentary feature work.

About 18 months ago, after a year of struggling with a broken third party API that almost brought a business to it’s knees by placing significant roadblocks in front of in house development, I was part of a team tasked with designing our own client facing API.  With no desire to expose other developers to the cruel and unusual punishments of software design we’d had to endure, we came to the conclusion that it was really important that we god this piece of the system right.  People say first impressions are everything, and your API design can make or break the faith other developers have in your ability to produce software.  Show somebody a shitty API and they’ll perhaps correctly assume the rest of your code sucks too.

The Best Man For The Job

There’s a bit of a trend that I’ve noticed with some of the worst APIs I’ve worked with: they seem to be designed by the wrong people.  The wrong people to design an API are 1) the guy that wrote the internal code to do the job the API is providing access to and 2) the consumer of the API. 

The guy that wrote the code that the API is calling under the hood will be inherently slanted to implement an API which exposes this functionality and will have a predisposition to creating a leaky abstraction.  This is especially bad for the consumer APIs designed by the internal implementer tend to assume the consumer knows far more than he really does, or has access to internal data that in reality, he doesn’t.

Conversely, an API designed by the consumer of the API will have a tendency towards solving problems that are not the concern of the API itself.  The consumer will, either accidently or by intention, attempt to offload some of the work that should be the responsibility of the calling code into the API.

Ideally, the person that’s writing the API will have knowledge of the system internals, but not be the guy that wrote them. A fellow team member with passive experience to the code would be a good person, or ideally, a pair design exercise between the person that originally wrote the code and an API designer, with the consumer as a consultant.

Speaking The Same Language

Like a lot of software development, you make good progress when you get your terminology right and understand exactly what you’re trying to produce.  I’ve consistently found that the best way to think of a client facing API is as a orchestrating thin wrapper that summarises, in code, a set of business processes that you wish to expose to the public.

In order to get your API design right, you need to clearly define and agree on the boundaries of the system with both your internal team, and your consumers.  It’s important that you have a clear understanding of the following:

• The responsibility of the calling code
• The responsibility of the API layer
• The responsibility of the internal code the API makes calls to

This might sound like a really simple suggestion but I’ve taken part in countless discussions where people on both sides of the API just “presumed” that either the calling code or the API would perform specific functions (data cleansing, logging etc) when in fact, this confusion had lead to none of the implementers bothering to write the required functionality.  Make sure you know for certain what your API is responsible for doing.

Defining Your API – Tips and Tricks

Defining your API methods (or the “contract” of the API) is the most important thing to get right and there are several vital things to remember.

• Choose Your Names Wisely Using the language of the business
  
  It’s vital that your API methods speak in terms that the caller is going to understand.  Your API should be readable.  If your users go hunting for the documentation every time they want to use a method, then you’re probably doing it wrong.

  Clarity in naming is exceptionally important.  The names of your API methods should succinctly state what action that method call is going to perform.  Don’t fear using long method names, embrace them for clarity.  As a general rule, your pmethods should probably always be in the form DoSomething(object withThis);

  Ensure that when naming methods you reflect business operations in the method names, not the underlying implementation.

  Bad example:     void InsertToTblCustomer(string[] custDataValues);
  Good example:   void AddCustomer(Customer customer);
  Good example:   void DisableAccount(string accountId); 

• Don’t pretend to be a data access layer

  APIs should summarise business operations in a logical and meaningful fashion.  You are not a public facing data access layer and you should never pretend to be.  If your users want raw database access give them read only permissions on some tables and a copy of SQL Management Studio.  So don’t write methods for CRUD operations in your API (unless you’re writing some kind of online file management utility).

  Bad example:     void InsertToTblCustomer(string[] custDataValues);
  Bad example:     void UpdateTblCustomer(string[] custDataValues);
  There are no good examples!

• Avoid leaky abstractions

  This is a fundamental and simple rule – don’t expose your callers to anything that they’re not interested in or won’t understand.  If it’s not important, don’t show it.  Don’t code for things nobody will ever need and don’t require your callers to have intimate knowledge of data types or internal categories in your system.

• Create a data contract between you and the calling code
  
  I’m going to borrow some of the terminology from WCF here because I’ve found it an appropriate label.  Create a Data Contract library for use in your API.  This library should summarise the business process and the outward facing view of your software.  It might contain terminology that doesn’t actually exist in the software itself, but in the business processes that the software models.  Either way, this, and only this, should be the language that the API talks to your callers.

  Where possible, create this data contract in a separate assembly that’s entirely decoupled from your core system and distribute it to people that want to use your API.  This is especially beneficial when using WCF as your clients can generate a service proxy and deal in the same data types that you are in your API code.

  It should be the responsibility of the API layer to marshal the data from your data contract into the domain model of your internal components.

  You data contract should contain every type used to communicate with your API and the object model should be named in a way which is meaningful for the consumers.

  Because your data contract is NOT the object model of your internal components, you’re able to add properties and objects that don’t logically exist in your internal components.  This means that you can perform an operation using some internal component, gather the output in your API layer and then compose the output data in a meaningful way using classes written specifically for the data contract.  This way, by the time the user has access to the output data, it’s in a format and language which they understand.

• Support standards!  Don’t reinvent the wheel!
  
  Here’s a true story; while working with an API, my team was faced with the following API method:
  object Run(string request);

  It was the only method on the API, and “covered up” for around 30 methods all made available through one giant black hole in the side of the system.  Underneath that there was an XML format that the request had to be in in order to call the appropriate method.

  If you’re writing an API, stick to some kind of standards.  Ideally, expose a web service endpoint with an accurate WSDL that people can call or use a simple and obvious REST endpoint.  

  Please, please, please, do not make other developer suffer by rolling your own delivery mechanism.  We have enough of them, don’t confuse people by adding some more.  If you’re going to use a raw sockets connection, supply a calling library and stick to some standard middleware like WCF rather than rolling your own. 

  Thousands of people have spent thousands of man years writing code based on existing techniques, you’re not better than all of them combined.

  Reinventing the wheel is never good for anyone.

• Ensure that the user can retrieve values they’re going to want to modify

  The number of times I’ve used APIs that let me set or update objects without returning the current state of the object is mind blowing.  So always remember: If you’re going to let them set it, let them get it.  Providing an update or “upsert” method without allowing your consumers to query the current state of data in the system is a complete waste of time.

• Supply compiled libraries to work with your API documentation

  This may not always be possible, but it’s a really good idea to supply a sample implementation and compiled binaries with your API that covers the most common scenarios of usage.  Not only does this prevent the consumer from struggling to get to grips with you API, but it allows you to outline and illustrate a set of best practices for usage.  In an ideal world, the user could just use your sample code in their application, so ensure you license the code appropriately.

  This is an exceptionally good way to deal with any authentication your API may require as you have the ability to provide additional helper classes to perform some common tasks (authenticate –> perform action –> logout, for example).

• Keep your implementation clean

  Delegate the API logic to your middleware components / reusable libraries.  Do your best to ensure the API layer doesn’t actually contain the logic required to perform operations, just the logic required to marshal the data from the API format into your internal data structures.  The API should simply orchestrate calls to one or more internal methods because your API should simply be exposing existing functionality.

  If the API is exposing some new, API specific functionality, consider splitting this behaviour into a separate assembly or binary to aid testability.

• Consider dogfooding

  Dogfooding is the act of using the software you’re creating.  I worked on a project where we were developing an order placement system in ASP.net MVC, and as part of the design process we decided that we wanted to have an API that was a first class citizen.  It then dawned on us that in order to produce the API in a way that accurately mirrored the functionality of the website, we should have the website consume the API like any other client would.  The website had it’s own concept of user authentication, and when a user logged in, the web application logged in to the API as the current user.

  Doing this not only ensured that our security model was watertight, but that any additional web functionality would immediately be available to API users because they were actually the same thing.  On top of that, you gain confidence in your own API because you know that it’s called often by your own code, reducing the likelihood of users discovering bugs in your API because it’s not a product you actually use.

• Support atomic operations including rollbacks on failure

  When implementing your API methods, ensure that if an exception occurs or an operation doesn’t complete, the all the changes made by your API call are reversed.  Consider explicitly supporting transaction scopes in your API to let your consumers compose their own “set” of operations.

• Support bulk operations where appropriate

  Building support for bulk operations into your API can often prevent performance issues occurring later when a user tries to, for example, insert 10,000 customers sequentially.  Consider pluralising your methods, so instead of providing an AddCustomer(Customer customer) method, provide only a AddCustomers(List<Customer> customers); method.  Doing this prevents callers from overloading your system by bulking data through your API in unintended ways, allowing you to properly cache required data and cater for these bulk operations.

  This isn’t always appropriate, however I’d always strongly suggest offering pluralised versions of methods that you suspect may be used in bulk, in order to help optimise your API calls and reduce the amount of data being transferred over the wire.

• Logging as a first class citizen

  Don’t wait until somebody asks about API usage to decide to log it.  Build logging into your API wrapper, from the start, at the point of every method call.  It doesn’t need to be fancy, and you can use a number of freely available components to handle these logs and log rotation (consider using log4net or log4j for simple log rotation).

  Log each method call and some summary or identifiable element of the data passed to it.  This’ll help you profile API usage, and identify how data changed in your previously closed system.

• Security as a first class citizen

  Consider the security of your API from the start of the project.  Understand who will have access to your API, which organisations and which individuals.  Do you require roll based security?  Do you need a way to disable API support for specific customers?  Are you transferring data that needs to be encrypted over the wire?

  Beware of over baking your security.  WS-* offers some very robust packet level security features, but if your API doesn’t need them, or is restricted to an internal network, then don’t bog down your implementation in unneeded security.  Beware of making security choices that tie you down to a specific protocol or technology stack – you want to keep your API usable for the consumers.  Do the simplest thing that works.

• Have integration tests!

  Make sure you have integration tests with mocking at the business logic layer. These tests are for your API wrappers, NOT your logic. The logic should be tested independently, you’re just ensuring your API layer, marshalling and method calls operate correctly at this level.

  With any luck, your business logic should already be tested as part of your existing test suite (which you have right?) but if not, ensure the business logic is tested separate from the API code.

  Consider using a TDD or BDD approach to designing your API calls, designing the specification first in the form of some calling code, then write the code required to make your usage examples compile.  This will help you understand exactly what calls the client will have to make for to your API to achieve specific functionality.  These tests can happily double up as regression tests when you make changes to the API.

• Keep it simple!  If all else fails, do what the big boys do.

  Always strive to keep your API simple.  Pretend your the consumer at all times.  If you’re unsure of how to proceed, I’ve always found inspiration, both for what to do and what not to do, from reading the API documentation of some large companies that have widely used APIs.  It’s safe to say that the likes of Amazon, Google and Microsoft have had to put some thought into their API designs.  Beware of trusting their decisions blindly, but liberally borrow anything you, as a consumer, would find pleasing in your API.

I’m not going to try and convince you that by following my advice that your API design will be flawless.  I’m really hoping for a little discussion on this topic as it seems like something that is rarely covered and often “felt out” by the people left to implement APIs for the public.  These are just some lessons I’ve learnt on the way while implementing several public facing APIs.

Want to talk about APIs?  Send me an email!

I feel frustrated at the moment by the endless cyclical debate on the internet (in this case, a comment on Kotaku) claiming games are creatively plateauxing due to their middle age.  People seem incredibly pent up on the games-as-art debate to the extent that they seem to deride anything that the "it’s just a game" argument could possibly be justified by. 

I want to open this up with a really simple sentiment: I love progressive, narrative driven games, but I sure as hell enjoy playing games that are just a game.  Sometimes I just want to be entertained.

The precise comment on Kotaku (by HarlequinRiot) "The industry needs to rethink what a game can be and use all this amazing technology to make new experiences that may not be so stratified as "this is you, go here, do x, listen to y". Gaming needs it’s Moby Dick or its Brothers Karamazov, as its Citizen Kane’s come every few years." actually struck me as opposing the notion of a "game as a game".  Games have rules and boundaries, a game without a good rule set is just "fucking about", and that’s why these kinds of games are either experimental or don’t exist – they most certainly don’t make money. 

I don’t always need a new experience.  I actually believe that amidst all these calls for innovation and change, that gaming is in the midst of a renaissance of innovation.  The industry is old enough now to learn from the successes of the past, while incrementing in small steps every year.  It’s really a shame to suggest that just because the core gameplay mechanic of two games are the same that they haven’t innovated in subtle ways that will be gathered into the collective unconsciousness of game development.  The simplest examples of this in action are the incremental games – look at any yearly sports title or Halo title or Unreal title, and you’ll notice little innovation year on year, but over 3 or 5 years there’s no way you can argue that you’re playing the same game.  I think people drastically undersell the innovation in game design that happens every day.

On Michael Abbots Brainy Gamer confab (part 2) posted yesterday (which I’d strongly recommend), one of the participants was strongly arguing the point of authorial intent and influence over a game property, implying that regardless of agenda, that a controlling authorial voice on a game imparts part of their world view on a product.  While I agree this is unavoidable in narrative works (especially in the likes of books and cinema), I honestly believe it’s a stretch to state that the guys that made Trials HD or Rocket Riot somehow accidently imprinted their world view on their products.  Even if the product is an inadvertent result of personal ideals, the strict confines of a game system oppose accidental messages in game design.

When the games that gain critical acclaim are generally none of the things that the critics seem to desire, it certainly shines a light on the critics themselves.  You can’t celebrate Super Smash Brothers Brawl or Trials HD, while complaining that a games like GTA4 or Gears of War is thematically simple, and then in the same breath complain that games aren’t progressive or sophisticated enough.  Doing so is pretty much the height of hypocrisy.  If you send these kinds of mixed messages to the people who write games without realising that there’s a natural path of development that must be travelled to get the medium to where you’d love it to be.  Games like GTA4 and Gears, even Bioshock, might not be "all you want them to be" but they are progressive thinking games that try to push both technology and storytelling forwards, even if their respective stories suck.

Likewise, it’s unfair to say that games aren’t sophisticated because they ape cinema, when actually, the most successful and celebrated "intelligent games" do so by emulating cinema and books.  Nobody seems to have a clear vision of what they think "sophistication" in games should really be.  Sophistication is often seen as production values by the mainstream gaming-media when really, the sophistication of the games rules and systems are a "purer" sign of an progressive game. 

I love narrative in games, but you can’t criticise a game for aping the conventions of cinema to achieve a strong narrative without stopping to realise that they only reason they ape that ape these conventions is because they’re effective, you can’t have your narrative without it.  This is especially noticeable when games attempt to forgo book / cinema narrative conventions in exchange for something more game oriented, when this happens you end up with Braid.  I loved Braid and I thought that it was fairly unique from a story perspective but flawed in the telling. The way it told its story played right into game mechanics, and as a result, the story came across as fragmented and confusing to the majority of players because the game mechanics used to present the story don’t naturally lend themselves to story telling.  When backed up by the authors refusal give anyone the answer, much of the message was lost. Regardless of authorial intention, if lots of your audience don’t understand the story or narrative you’re trying to convey, you’ve failed as a storyteller and end up being accused of pretention for doing something "different".

A more recent example of "emergent storytelling" would be the well reviewed "The Path".  I enjoyed playing the path, but honestly, it utterly fails as a game.  It’s a terrible game.  Interesting and thought provoking as an experience, but an horrible game.  The controls are awful (practically digital, PS1 era 3d game controls), the interface is counter intuitive and the tasks are deliberately obtuse.  I still enjoyed it and rate it highly, but it failed at being a quality game while succeeding as being a quality experience. 

I think that really sums up a lot of the progressive discussion on videogames – people want something more from their entertainment, but it isn’t games.  Maybe the engineer in me is being pedantic about naming, but I’d much rather "interactive entertainment" for software like "The Path" than "videogame".  Game is a loaded term, and along with it come certain expectations; a set of rules, some gameplay mechanics and a way to progress.  I believe games can be more, I believe games can tell stories, make you feel and make you think, but I don’t think those are required aspects of a good game, games can be "good" outside of those constraints, as an exercise of entertainment through gameplay mechanics.  You can’t criticise a game for being too much like a game, it’s like criticising a book for not being a film.  I really believe that a game can involve art, but if the game "becomes" art?  Well, then you’ve got art that’s art first, game second.  That’s valid expression, but it’s intention is to be art.

On the same podcast there was more talk of the recent debate around Shadow Complex, and the reaction of people towards Orson Scott Cards involvement in regard to his personal politics.  Just a quick note really; the mainstream doesn’t care about your protests.  I really mean that.  You’re telling me that you REALLY think people will boycott Activision because of their (sexist) Sin To Win advertising campaign?  Really?  It’s "just" marketing.  That doesn’t mean I don’t think it was excluding, but what it does mean is that I see sex and inequality used to sell products every single day of the week.  If you stopped buying everything that a person you disagreed with had worked on or had sex used in it’s sales material you would run out of things to buy and games to play pretty quickly.  And that’d be just you, because of the people that know about some perceived protest-able injustice so insignificant, not only will half of them not care, but most of the people that do care will do whatever is most convenient to them when a product comes along that they’re interested in.  This goes doubly for marketing, an industry that frequently abuses both it’s position and people to sell product.

While this may seem like a negative response to the confab podcast, it really isn’t.  I enjoyed listening to it, as I have in the past, and have plenty of respect for all of the people involved, some really interesting thought provoking stuff on the direction of gaming comes out of it and I’m really looking forward to the following 3 episodes.  The Brainy Gamer is still one of my favourite gaming resources on the web and certainly occupies the most prominent position in an interesting discussion.

There are plenty of quality, innovation filled games on the market, many of them produced recently.  As for most of the critics?  Part of the problem and not part of the solution.  It’s all well and good to criticise game design inadequacies, but until you’ve really considered the design of compelling, fun, game systems as part of your argument, I’ll write off your "innovation is dead!" arguments as hot air.

A common complaint when faced with localizing ASP.net MVC pages is that littering your code with tonnes of runat=”server” tags breaks the “purity” of the MVC model.  Regardless of how meaningful that debate is, there is a way to achieve globalisation without server controls.

I’m going to walk you through a sample implementation which should hopefully make this clearer.  As a standard disclaimer, none of this code has been tested in a production environment and I wouldn’t advise implementing it blindly.

I’m going to attempt to play this out mostly in screenshots…

The Idea

• The required language is stored in a database / session / extrapolated from the Url route information
• Your view pages derive from the type TranslatableViewPage

• This page adds support for a LanguageCode property that you can make use of inside the view along with adding a class implementing ITranslator, a class that provides hooks into a translation database.

• This controller add a method called ViewInLanguage(string languageCode) that you use instead of View() or View(model) to return your Asp.net MVC view.

Class Layout

The following is built upon the standard Asp.net MVC starter project for the sake of illustration.

Implementation

First, configure the translation settings and register your translator…

You need to configure a fail-safe default language code and a type that implements ITranslator.  This translator will be responsible for doing the heavy lifting.  Ideally we’d add some inversion of control here to allow you to define the translator implementation at configuration time, but that’s outside of the scope of this example.  I’ve implemented a very crude resource .resx translator for the example.

Next, make your controllers inherit from TranslatableController

Once inherited, switch from using the View(); method to ViewInLanguage() passing in your desired language code (gathered from the user session / database / Url route).

Then set your view type (or derive your view from) TranslatableViewPage…

Once your view is inheriting from TranslatableViewPage, you’ll have access to an instance of your specified Translator and the LanguageCode inside the view which you can use in a manner similar to the built in HtmlHelper class to access your translated strings.

How It Works

The TranslatableController provides you with ViewInLanguage and when called generates the standard MVC ActionResult.  This ActionResult will be a ViewResult, which is then wrapped in a LocalizedViewResult wrapper class adding a LanguageCode.

When ExecuteResult is called on the LocalizedViewResult to render the view, the LanguageCode is placed in the TempData array in the TranslatableViewPage.  Then, when the OnInit(EventArgs e) method is called on the TranslatableViewPage, this LanguageCode is extracted and placed in the LanguageCode property on the page.  In addition to this the page provides a constructed instance of ITranslator which you can use in your views to source translated data as the page is rendered.

Source Code

Download Here

A quick note: I’ve upgraded MobileTFL to version 1.0.0.9.

Get it here.

+Fixed critical bug due to data format changes.
+Reworked parsing of source data so it’s less sensitive to format changes in the future.

Apologies for the rapid releases, but hopefully the app should be good “long term” as of this release.
There will be one further release in the near future consisting solely of cosmetic changes.

A quick note: I’ve upgraded MobileTFL to version 1.0.0.8.

Get it here.

+Improved loading speed (less start up lag)
+Fixed critical bug due to data format changes

I’m planning on listing this app on Windows Mobile Marketplace when it launches later in the year for a small fee (£1.50 ish).

Don’t be alarmed if you see this happen. The software will remain free to download from the web (likely relocating to www.electricheadsoftware.com), however there will be above mentioned small fee for those wishing to show support / download it off Marketplace to cover initial costs (certification / enrolment in Marketplace isn’t free).

I’m looking forward to seeing how well a small utility app can do in the wider Windows Mobile “consumer” market as a test bed for a few future projects. I’d appreciate it if people showed support if they fell it appropriate.

I’ve not written in awhile as I’ve been busy moving to the other end of the country.  I’m now in London (Clapham Junction) rather than Manchester and slowly but surely settling in to my new life.  I’m still living out of boxes and preparing for an ISP change, so I’ve not really had time to do too much development (on a laptop, please, the poverty!) but what I have been able to do is play a good load of Xbox 360 games.

So a little executive roundup, in order of release…

• Bionic Commando
  
  Interesting one this, I didn’t pick this up on release week, as I have a habit of doing with most games that look “premium” due to mixed reviews floating around the web.  I think it was the Kotaku review that swayed me to pick it up (that and a £30 price point in Tesco the week I was packing all my belongings into boxes).  I actually really enjoyed the core game play mechanics of BC.  I went in expecting something like Crackdown and didn’t get it.  What I did get was a pretty tight modern 3d Contra game.  The internet said it was difficult, and after initially being disappointed that it wasn’t, the game spent the final third of the game throwing three hundred sodding mechs at you at the same time.  Enjoyed it up until then… oh and the end of the game is hilariously bad / amusing / poor / brilliant. 

  Enjoyable, but I’m not sure if I’d recommend it.

• Fuel

  I looked forward to Fuel coming out.  I liked the previews, I thought it looked really decent.  I like Fuel but it’s not a good game.  Fuels gimmick is that they’ve used satellite imagery to render an massive open game world (talking hundreds and hundreds of square kilometres of, well, dirt) and thrown a bunch of “extreme” weather in there.  Only, the vehicles don’t remotely handle like cars, the core game play mechanic of “racing” is really poorly implemented (you loose every race until the quarter of the final lap, then get to catch up) and generally there isn’t too much game to be had.

  Thankfully there’s a free roam mode, where you collect car customisation bits that make not a single piece of difference to the game play experience.  Fuel is just plain boring and I can’t recommend it to anyone.

  However, I oddly find myself enjoying Fuel.  I like exploring the largely bland (think Yellowstone National Park but with some poor texture work) massive environments, driving in one direction for literally half an hour (the map really is that big, big enough they let you teleport around it). It’s somehow therapeutic. So I guess, while I can’t honestly recommend it, you might enjoy it if you like endless sandbox driving.

• Red Faction: Guerrilla

  I’ve only really spent about 3-4 hours with Red Faction, and only with it’s single player.  I really really like Red Faction, but honestly I just got really bored playing it after awhile.  The core game mechanics behind the game are brutally fun.  Everything explodes, literally everything.  The combat is pretty difficult, and blowing up just about every building in the game is incredibly fun.  Unfortunately the game is set on Mars, so everything is red.  And I mean everything.  If you think Quake looked brown, just wait until you see the red in this.

  The tech behind the game is pretty excellent, there are tonnes of excellent pacing mechanics to lead you through the open world game, they stage game progression pretty well, but it’s all a little… soulless?  I don’t know, something just didn’t quite grab me despite the game clearly being excellent.

  I guess I’ll get back to you on it.

• Prototype

  The game where you get to karate kick a helicopter.  Seriously.  When I turned Prototype on I was pretty disappointed – largely because the texture work throughout Prototype is actually woefully bad.  Like really, 2003 Xbox game bad… and then three seconds later they give you the super-powers of Spiderman, The Incredible Hulk, Wolverine and er., Bionic Commando.  At once.  Prototype is equal parts a kind of rubbish looking version of Crackdown with a far far worse environmental traversal component and part Devil May Cry rip off (I don’t rate DMC) where you play, to the best of my knowledge some angry hoody.  The story is trying to be graphic-novel cool along with dramatic and really, it’s just utterly lame.  But you don’t care, because the game play mechanic is incredible FUN.  Not clever and not big, but you get to use your weird whip arm to pull helicopters out of the sky and sprint up skyscrapers while fighting mutants.

  I really can’t say a bad thing about a game with a core mechanic so fun that it overcomes both terrible art assets and a woefully bad story, two things that I tend to hold in high regard.  I’d recommend it.

Oh I’ve also purchased and got re-engrossed in Fallout 3: The One That Raises The Level Cap To 30 And RetCons Out The Ending. Fallout 3 is pretty much still my game of last year, so being able to continue made me very very happy.  Looking forwards to Telltale Games’ Monkey Island episodes that start tomorrow and I’m positively lusting after Mass Effect 2 after the E3 teaser (along with, surprisingly, New Super Mario Brothers Wii).

As ever, make your own decisions, but I’d recommend you check out at least a few of the above games.

One of the most valued practices in software development is brevity.  Writing code is bad.  When you write code you create bugs, and creating bugs is bad.  The solution?  Don’t write much code.  Commenting your code however, has traditionally been seen as a “good thing”.  So much so that most modern programming environments make some provision for document generation and offer style-guidelines for commenting your code.

I believe, however, that excessive commenting is actually an anti-pattern and should treated with caution, and as far as possible, avoided.  I’m going to illustrate my point with a (somewhat contrived, but in no way unusual or outlandish) example.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace XmlDocumentationAntiPattern
{
    /// <summary>
    /// XmlCommentHell
    /// </summary>
    /// <example>var xmlCommentHell = new XmlCommentHell</example>
    public class XmlCommentHell
    {
        /// <summary>
        /// Description
        /// </summary>
        /// <remarks>String description of XmlCommentHell.</remarks>
        /// <example>instance.Description = "some description";</example>
        public string Description { get; set; }

        /// <summary>
        /// XmlCommentHell ctor
        /// </summary>
        /// <param name="description">Description string</param>
        public XmlCommentHell(string description)
        {
            // Assign description
            Description = description;
        }

        /// <summary>
        /// Gets the description property, but in reverse!
        /// </summary>
        /// <returns>Reversed description</returns>
        public string GetReversedDescription()
        {
            return Description.Reverse().ToString();
        }
    }
}

The context of this example is C# but similarly applies in other programming languages.

If you find yourself engaging in XML comments like the above example, I really believe “you’re doing it wrong”.  Why?

• Reduced code readability

  The Xml comment clutter in the code above actually reduces it’s usefulness.  The code now takes three times as much screen real estate to maintain and understand.

• Low signal to noise ratio – too many characters that add no value

  When you’re maintaining systems however large, the act of actually writing code takes time and adds maintenance overhead.  Past the visual unpleasantness the amount of mark up required to document relatively simple methods actually reduces the codes utility.  Only ever type ANYTHING in your IDE if it adds value.

• Incredibly obvious comments

  There’s a wonderful quote to the tune of “always pretend that the person that’s going to maintain your code is an axe wielding manic who knows where you live”.  I’d like to extend that by adding “so don’t insult their intelligence”.  There are few things I find as frustrating as reading comments that not only add no value but also make me feel like I’ve wasted a tiny piece of my life reading them.  Don’t waste your time or mine.

• Violating the DRY principle

  The DRY principle is very well agreed upon in software development.  Don’t repeat yourself.  If your XML comments just repeat your method signatures, you’re not only repeating yourself (and thus wasting time) but you’re leaving yourself open to a maintained nightmare as the code changes and the comments are left unchanged leading to confusion and misinformation.

• Possible misuse – the generation of utterly useless documentation

  When I see projects documented in this way I often joke that someone should run Sandcastle or javaDoc over the code to gain some tangible value in the form of MSDN-esq documentation.  I’m actually wrong.  This is a terrible idea.  Pop quiz time!  What’s worse than tedious documentation that adds no value?  Tonnes of hyperlinked documentation that adds no value!  Think of the poor developer wasting minutes to hours searching for the value in generated documentation before painfully realising that there’s none to be had.

I occasionally get met with some resistance when I state my opinion on this for a couple of reasons.  People often argue that they do it for the sake of intellisense and IDE tooling, that they do it for generated documentation or just out of habit.  I feel like these are all dangerous reasons.

Firstly, if you’re generating documentation for documentations sake, you’re either trying to please some form of middle management that doesn’t understand what documentation really exists for (hint: to help developers develop), or you’re wasting time.

Secondly, if you’re documenting methods for intellisense you’re probably missing the point.  See, intellisense and other IDE self-help mechanisms are very good; they’ll display method signatures and method names with minimal fuss, any extra comments you glue on top of every method will either clutter your GUI, or become ignored white noise, potentially leading to that one important comment going ignored as your developers slowly desensitise themselves to reading the human generated “auto-doc” garbage.

Finally, if you find that you need to cover your methods in comments because they legitimately don’t make too much sense at a glance then you’re falling foul of a different problem: you have code that’s not legible maintainable and clear.  In this case you’d be far better served by ensuring your methods are named well, take logical parameters and have single clearly defined purposes.  In my experience, whenever somebody says that they need to comment their methods because the method is unclear, they really should be refactoring, not documenting.

Please DON’T bury your code in comments, just keep it all readable ok?

There was a piece on Kotaku this weekend looking at the development at AI in games, It specifically set out to ask leading figures what they thought of the development of virtual “beings” in games,

“Kotaku set out to ask experts in the fields of Hollywood movie magic, theme park creators, robotics experts and AI specialists to answer the question: Do the AI-controlled characters in games qualify as robots or some other form of artificial life. Are those creatures who are at the player’s mercy in Lionhead Studio’s Black & White games truly virtual beings?”

Inside the article was a rather worrying quote from self declared futurist Thomas Frey, executive director of the DaVinci Institute,

"In short, our games have indeed evolved into crude life forms," said Frey. "Innovations in the digital world are happening exponentially faster than in the material world, so the digital beings in games will soon become far more lifelike, and will eventually step out of the screens and exist as 3D avatars, interacting with us, much like other people."

I always get a little upset and slightly concerned when people from places like the DaVinci Institute (from their "about us" page: "Launched in 1997 as a non-profit futurist think tank, the Institute has emerged as a centre of visionary thought, attracting both a national and international following of idea junkies and business leaders alike.") start to talk about things like programming and AI.  I always feel like these kind of think tanks highlight a bit of a problem with the development of new technology.

All you learn is that "futurist thinkers" actually have no grasp on the practical implementation of the technology.  I’m all for creative thinking and speculation, but somehow implying that very simple game mechanics are going to develop rapidly and with little to no point into some Skynet like Ai is simply absurd. 

Thankfully the Kotaku article actually asked someone with half a clue (Chris Darken, conference chair for Artificial Intelligence and Interactive Digital Entertainment and an associate professor of computer science at the Naval Postgraduate School) who equated videogame AI to an expert system.

In all honesty it’s a stretch to even call them that.  The problem domain that your average game AI lives in is so rudimentary small that I’d rather use a phrase closer to "novice system".

Game AI is nowhere near close to simulating human behaviour, near all "humans" are scripted, and the most simulated behaviour comes from games like Spore or The Sims where the actual behaviour is so generalised (eat/sleep/mate/die) that any nuance of actual behaviour is lost and what results is little more than a general abstraction to suite the purpose of game mechanics; which is utterly perfect for the task at hand, because honestly, developing something more sophisticated would be a huge undertaking with no practical benefit to the game project.

I’m honestly perplexed as to why some gamers seem to think building “AI” is appropriate for a game.  The term AI is exceptionally misleading and would likely never be appropriate unless you were working on something that wasn’t as strictly defined as your average “regular” game environment.

Imagine playing a game where a key NPC suddenly decides that they just weren’t into the plot anymore and just stopped playing, a “real AI” of this nature just isn’t for purpose.  I’m not suggesting that what we perceive as “AI” in games doesn’t have room for improvement, far from it, I am however suggesting that games will never lead to developing a “true” AI, simply because it’s not an appropriate avenue to approach game design from.

People need to realise that good path finding is not the same thing as intelligence, and that they probably wouldn’t actually enjoy a game where the AI attempted to simulate sentience.  It’s work enough dealing with other players in a multiplayer game, let alone having to contend with a simulated intelligence in a single player oriented experience.

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.