Designing a great API
Several years ago I worked on a payroll package developing a core engine that required an API to let third parties write calculations, validations and security gates that would execute as part of it’s regular operation.
We were a small team and I had many conversations with another developer tasked with building a payroll using the API I would provide. Some methods here, classes there, the odd helper function and I had an API and then we had a mini payroll running.
Then he showed me the code he had written and that smug grin dropped off my face. It was awful.
Perhaps this other developer wasn’t as great as I’d thought? Looking at the code though made me realise he had done the best anyone could with a terrible API. I’d exposed parts of this core payroll engine with hooks when it needed a decision. Its job was to run the payroll – a very complex task that involved storage, translation, time periods, users and companies. That complexity and context had leaked out.
Unfortunately it’s not a unique story – many API’s are terrible to use. They’re concerned with their own terminology, limitations and quirks because they are exposed sections of an underlying system developed by those responsible for the underlying system.
If you want others to have a good experience with your product you have to put yourself in their shoes. Whether it’s a UI or an API makes no difference.
You are not the user
That’s the real difference between writing the classes that form your regular implementation and those that make up your public API.
We had time to fix our payroll API. Instead of refining and polishing here and there we took the 20 or so snippets developed for the mini payroll and pruned, cleaned and polished until they looked beautiful. They scanned well and made sense to payroll developers unfamiliar with our package. When a third developer familiar with payrolls but unfamiliar with out package developed the necessary code for a fully-functional jurisdiction in record time with minimal assistance we knew we had hit our goal.
Sure implementing that new API was hard work. Instead of simple methods sticking out of the engine we had a facade over our engine but it was justified. They were two different systems for two different types of user with distinct ideas about what the system was and how it was going to be used.
Code First
Many years later I found myself on a small team of 3 people tasked with putting a brand new API on top of Entity Framework for configuring models with code the .NET world would come to know as Code First. I was determined to use my experience and avoid another complex API surface littered with terminology and leaky abstractions. Parts of EF already suffered from that problem.
So for the first few weeks of that project we didn’t write any of the code that would in fact become Code First.
Instead we decided who our user was – in this case a C# developer who likes writing code, knows LINQ and some database concepts but doesn’t know Entity Framework as people who did were already using Model First or Database First.
Then we wrote tiny sample apps and tried to find simpler and simpler ways to describe them in code. We’d often start on a whiteboard with a scenario and write the complete mapping. We’d then try and find conventions that would remove the need for most of it and then try to write succinct code to configure the rest. As the newest guy to the team I’d fight to keep EF terms away from the main API surface in order to reduce that barrier to entry and help drive adoption.
Finally we’d hit the computer and develop stub classes and methods to make samples compile and let us try the IntelliSense. This isn’t always necessary but if you want to develop a fluent API or provide lots of type-safety such as Code First’s relationship mapping it’s highly recommended.
We’d then revisit the samples later and see if they could be read as easily as they were written and figure out what problems people were likely to run into and whether we could solve them without too much noise. Sometimes this meant having more than one way to do things such as chaining the fluent methods or allowing a bunch of properties to be set (solved with an extension method class providing the fluent API) and how users could manage larger models (solved by subclassing EntityConfiguration<T> – now EntityTypeConfiguration<T> sigh – and allowing redundant specification for things like relationships that span more than one class).
We finally ended up with succinct code like this with IntelliSense guiding you along the way and preventing you from even being able to specify invalid combinations. The HasMany prompts the properties on Customer and it won’t show you WithRequired unless it is valid. In the case of Required to Required it will ensure that the WithRequired specified which end is principle and dependent. In short it guides you through the process and results in highly readable code.
Entity<Customer>().HasMany(c => c.Orders).WithRequired(o => o.Customer).WillCascadeOnDelete();
This process took a little longer but given the amount of use the API will get that time will be saved by users countless times over.
Code First went down incredibly well with both the target audience and existing EF users and inspired the simpler DbContext interface that became the recommended way of accessing EF.
I think it’s one of the nicest API’s to come out of Microsoft and .NET.
[)amien
PS. Martin Fowler has some great guidance in his book Domain Specific Languages.
My one-year check-in with my Windows Phone 7
It’s been almost a year since I bit the Windows Phone 7 bullet and put my iPhone 3G away. As a long-time Mac fan (our house is nothing but Macs) I wasn’t sure I’d last…
Contact & calendar management
Contact and calendar management is truly awesome as I wrote about previously. With the latest mango release Twitter and LinkedIn get brought into this unified system and messages that start with a text message can switch in and out of Facebook and Live Messenger as available.
What has this meant? Over the last year I’ve barely had to maintain contacts. Whenever I need to get hold of someone the information is there. If I want to see what they’re doing, it’s there. You can pin people to your start menu so having it automatically pick up a photo from a service is another bonus.
My Windows Phone is better for this than any other system I’ve used including my desktops.
Gorgeous user interface
The metro user interface is beautiful to use. It’s clear, fluid and fast and makes using the phone a breeze. You can see why Microsoft are adopting a similar user interface for their upcoming Xbox dashboard and seeing how far they can push the concept in Windows 8.
Such a bright fast user interface works best on the AMOLED displays such as that on the Focus – the LCD refresh rates on the HD7 for example seem to struggle with scrolling resulting in a shimmering on the screen.
Tasty Mango
Hardware choice
I currently own a Samsung Focus on AT&T and regularly get to use both a HTC HD7 on T-Mobile and a HTC 7 Trophy on Verizon for testing.
Having a choice of hardware is great – you can pick the screen size (from 3.5″ to 4.7″), type, speed (1GHz to 1.5GHz) and specifications including slide-out keyboards, microSD expansion slots, a waterproof model and up to a 13.2 megapixel camera.
The negative side of having choice is that all the devices I’ve used have a combination of matt and shiny plastics none of which have the same quality feeling as the iPhone 4′s aluminum and glass. The LCD displays and the Super AMOLED with it’s PenTile display also don’t look as gorgeous as the iPhone retina display and has a sort of dithered effect with some solid colors when viewed closely.
Here’s hoping the Nokia Lumia 800 raises the bar.
Most favorite apps available
The thing that really made the iPhone were apps. The good news is the best ones are also on Windows Phone 7 too often making better use of the display through the metro style they adopt.
There are of course many extra great applications and games available in the marketplace and games usually count towards your Xbox LIVE gamerscore :)
Some notable omissions still exist including Pandora (can play on the site though) and Skype (only a matter of time given Microsoft’s acquisition).
Some cool extras
Hidden features
You can also check and tweak all sorts of settings via the diagnostic options.
Microsoft’s extra free apps
Microsoft put together a bunch of slick small free apps that perfectly complement the metro style look and feel. They include:
The niggley bits
While most of the WP7 experience is great there are some rough edges that even Mango hasn’t yet sorted out.
Overly sensitive buttons
It’s actually great having a back button and prevents wasting screen on a back button like iOS does. The problem however is that both the back and search buttons are overly sensitive. It’s difficult to hold the phone in one hand and use it without your thumb hitting the pesky back button. It’s unfortunately something even the Xbox 360 slim picked up with the eject mechanism which is suitably annoying when putting away a controller.
Microsoft should add code to limit button presses to a distinct no-touch, touch for 0.4s, no-touch process.
Volume control
For some reason the phone has only one volume control that is shared by both applications and the ring-tone so if you’re the sort of person who like your phone low and your music loud you’re going to be constantly shifting back-and-forth and in my case that results in either embarrassing rings when it should be silent and silent rings when it should be working.
The volume control needs to be context sensitive. When in an app or the background music player is active adjust the audio volume otherwise adjust ringer volume.
Equalizer settings
There’s no sound equalizer settings so if you don’t like the sound coming from your speakers or headphones you’re stuck with it.
Build in a system-wide equalizer that at least affects the background music player.
[)amien
Typography can be fun
People are always surprised when they hear you’re interested in typography. The appreciation and interest in the shape of letters and symbols is definitely a little more unusual to find as a hobby but it’s actually quite fun!
Here’s a few ideas I hope will prove my point.
Play games
The Rather Difficult Font Game
This game shows you some text in a certain font then asks you to name the font from one of them in the list. It isn’t as difficult as the name sounds!
Deep Font Challenge
Head down to the shooting gallery to blow away the letters from the typeface he wants or doesn’t want.
Cheese or Font
Hmm, it’s odd how cheeses and typefaces often have similar names. See if you can tell the difference.
Kern Type
Many fonts contain extra information telling the computer how to adjust the spacing between individual pairs of letters. If you think of an AV for example the top of the V might start before the A ends or be very close. This game lets you move the letters around until you think you have optimal spacing then you can see how well you did.
Shape Type
The ultimate font game! See if you can reshape disported letters back to their original forms by adjusting the lines and bezier curves. The computer will score your efforts by comparing to the original.
Find a font
FontShop newsletter
This newsletter is both infrequent and interesting so it gets to come directly to my inbox. It contains interesting new fonts, news and designer spotlights and is a great way of discovering new typefaces to use.
IdentiFont
Asks you a series of specific questions about letters in the font on a continual process to narrow it down to the hopefully right one.
WhatTheFont
This tool is a little more automated, upload the picture and it should identify the letters although you may need to fine-tune the recognition (also available as an iPhone app)
So you need a typeface infographic
This flowchart takes you through a bunch of decisions to choose a typeface. Don’t expect to find anything too original though!
Smarten your site
If you have a web site you might want to look at using a custom font to help stand-out from the crowd now that they are compatible across many browsers. Yes, I should do this for damieng.com :)
Font Squirrel
Font squirrel have a great site full of many free fonts and have prepared the necessary font and CSS files required for the subset available for use on web sites.
Google web fonts
Google have almost 300 fonts available in their free web font directory right now and with just a couple of clicks can provide the necessary HTML, CSS import or Javascript necessary to use them in your pages. The fonts are served up from their servers too so you don’t need to worry about files or bandwidth.
Fonts Live
Monotype’s hosted service is similar to Google’s but contains just their own commercial fonts including well-known ones such as Museo, Gill Sans, Bodoni, Rockwell and many of Microsoft’s typefaces. Prices start at about $40 a year for small sites (250k visits a month) but they have 30-day free trials.
MyFonts WebFonts
MyFonts have a huge collection of fonts – some 40,000+ – most of which are available to use on the web for the same price as buying the font. This makes it cheaper than FontsLive but you need to host the files and CSS on your own server.
Offline fun
Playing cards
These Helvetica based playing cards are very stylish, bold and modern. If you’re going to play cards why not do so with something a little different.
Typographical calendar
Get a daily dose of typography in this compact little desk calendar. The designer’s equivalent of a word-a-day.
Helvetica The Movie
Not just a movie about the design of this iconic font but also the modern movement it was part of. If you like this keep an eye out for Linotype: The Movie due in Feb 2012.
Typography t-shirts
Zazzle has a lot of typography t-shirts as does TypographyShop and Ugmonk.
Create your own
If any of that has been enough to pique your interest why not have a go at designing your own font?
FontStruct lets you start simply by building your own from a library of pre-build shapes you place on a grid. It’s like LEGO for typography and is very easy go get started.
If you have an iPad then you can also try out iFontMaker for an easy way to make hand-drawn fonts (it lacks fine editing facilities). I actually used a Pogo Sketch for my Damien Typewriter but it is too soft so you could try other styluses. Once you’re done it publishes to their web gallery where you can download the TrueType font and a Web Font too.
If you enjoy that but crave more control then try the free FontForge editor which runs on many platforms and lets you create real fonts or hack apart other peoples (remember to not redistribute changes to other peoples fonts unless the licence allows it).
If you get stuck on some letters then try my favourite Designing Type book that devotes a page or two to each common character and shows how a number of well-known typefaces express it.
[)amien
Android’s Roboto system font for Ice Cream Sandwich
Google have switched system font for Android’s latest release (known as Ice Cream Sandwich) from the Droid Family to a new typeface known as Roboto.
Typographica opened today with a critique of the Roboto font which boils down to this:
The similarity to Helvetica is obvious but that similarity can be drawn with many modern typefaces – the other comparisons are tenuous indeed:
Yes, some of these differences are subtle when you put them side by side but subtleties are what give the typeface its character.
There are only so many ways to draw letters with consistency and readability especially if you want a modern sans look. That’s exactly why copyright refuses to cover letterforms in the USA.
So coming to the font itself at first glance, yes, on my laptop it doesn’t look as pretty as Helvetica when blown up for comparison but here’s something you should consider.
Typefaces are designed for a specific environment
Consider the following typefaces:
Use a typeface outside its intended environment and you’ll easily believe it’s a bad design, ugly or unrefined as those very characteristics that made it great for that environments completely fail to fit new surroundings.
Even the famous Helvetica has an environment of whitespace, bold colours and clean-lines where it shines. That makes it a top choice for corporate logos.
Roboto is the work of independent type designer Christian Robertson and until I see it on a Droid device I’ll cut him and Google some slack – from the screenshots I’ve seen online it looks like a good fit.
You have to at least respect Google for continuing to improve typography by commission fonts. Microsoft are the only other major UI player doing this as Apple’s sole contribution to typefaces in the last 10 years has been a hack-job on the open-source Deja-Vu Mono to rename it Menlo, move some bars around and to trash the hinting in the process so they have something to replace the ageing Monaco with.
If you want to download the font yourself here is a complete set of the files taken from the SDK (unlike the other zip floating around this one has all variants + the licence).
Download Roboto Font Family (ZIP of TTF) (399 KB)
[)amien
