You can find a list of the European talks on the developer portal. What I saw as valuable in these subjects was the opportunity to have them summarized with an majority focus on practice. Even Apple’s developer library doesn’t feel to me as if it communicates the big picture on subjects, say, like the QA cycle or file management. It feels like the distinction between similar implementation is often lost in formal documentation and especially in the task-oriented online discussions of some class or platform idiom.

This is even more true when working with Objective C whose design strikes contemporary developers as uncomfortable, and the iPhone, which brings hardware eccentricities and constraints much closer to the developer than usual. Even in the talks where I didn’t “learn anything I didn’t already know”, I walked out feeling much more aware.

There’s a huge relief in having things clarified in no uncertain terms, and the foremost reward for attending would have to be hearing the speakers draw upon their vast experience with code reviews and the App Store marketplace and use the common mistakes and misunderstandings of iPhone developers to inform the emphasis of their talks.

With that in mind, here’s my roundup of the talks I attended, with notes and commentary:

TALK 1: iPhone Tech Talk Kickoff

This was the opening state of iPhone development address, if you will. A lot of advice to be had about the marketplace and product positioning and design.

• Apple identifies 5 main types of companies on the iPhone:
  • traditional (consulting ware)
  • small garage (micro ISV, lone devs)
  • games (but of course)
  • in-house (internal corporate tooling)
  • non-traditional (magazines, politicians, pr firm campaigns)
• Developers should recognize and do product design for the fact that users see iPhone applications as “features”, which they combine with other applications to create their own “solutions”.
• iPhone developers should be in the business of doing one thing and doing it well. This adage was repeated many, many times throughout the day.
• Simplicity is important in light of change. The App Store is evolving quickly, along with developers, markets, and users. Technically, simple things support change better than complex ones. Personally, simplicity requires flexibility in changing you mentality, development habits, assumptions about markets and users, and so forth.
• Great applications almost follow an ingredients list. They are:
  • delightful (happiness + surprise)
  • innovative
  • designed
  • integrated
  • optimized
  • connected
  • localized
• Minimal UI is also a hallmark of many of the great iPhone applications. Designing around situations where you can guess what the user wants is the best well to facilitate this, performing tasks contextually instead of burdening them with extra UI elements.
• Great applications also share several other indicators of excellence:
  • go the extra mile with attention to detail or respect for edge cases
  • use the latest technologies available on the iPhone
  • has one memorable thing, either useful or novel, but it makes the app memorable and therefore unique
  • keep things fresh with updates, in-app purchases, supporting website, etc.

TALK 2: Effective iPhone Development Part 1

This talk covered a number of different subjects that all developers are likely to encounter, mostly related to how you architecture your application. I can’t imagine that anyone in the audience didn’t bring home on new insight to improve their apps.

• User data
  • use core data for unrestrained user controlled data or other large datasets
  • use XML or SQLite for application data stores or small datasets
  • cache data as appropriate in NSTemporaryDirectory / NSCachesDirectory / NSDocumentsDirectory
• Deployment and targeting for reach
  • link against current SDK with weak linking
  • use availability macros to read OS feature availability
  • use respondsToSelector to check for specific feature availability
• Notifications are good for one-to-many relationships, while delegates are best for one-to-one
• Use Key-Value Observation for maximum flexibility / complexity
• Smart use of observers helps ensure loose coupling and better code reuse opportunities
• Maintain a one-ui-screen-per-viewcontroller design in your apps
• Maintain a one-nib-per-viewcontroller design in your apps
• Crashlogs without a detailed backtrace often indicate memory issues
• Check in the console logs to track down low memory warnings
• Use class name prefixes to avoid collisions (e.g. NSBlah)
• Avoid underscores in names (they are potentially reserved)

TALK 3: Effective iPhone Development Part 2

A continuation of the previous talk’s litany of advice and insights. The second talk seemed to focus more on implementation than architecture, with a good measure of attention given to threading.

• Stay focused, i.e. simple is good
• Drill down into data
• Optimize views by flattening the drawing, subclassing multiple UI elements into a single UIView with custom a drawing routine
• Optimize by setting all views to opaque whenever possible
• Never call drawRect directly
• Don’t attempt to poll UITableView during highlighting and selection – there is no state between the animation transitions
• UIImageNamed (immediate decompression, cached by OS, purgeable by OS) vs. ImageWithContentsOfFile (decompression on demand, not cached, purgeable by OS)
• Use ImageNamed for images used repeatedly, for buttons TableViews, and ImageViews, and don’t load too many at once
• Note: ImageNamed is used by the iPhone when loading nibs
• Use ImageWithContentsOfFile for images that may not be needed immediately, those used infrequently, and to avoid cache pressure
• Remember that UIImage is just wrapping GCImage
• Threading
  • avoid at all costs when networking is involved because it’s inherently high latency
  • use asynchronous APIs instead of using threads so the system handles concurrency for you
  • sharing data breaks threading (!!!), transfer ownship of the data instead
• NSOperation simplifies concurrency by keeping object access confined to one thread, which is a best practice threading pattern, and it lets you forget about locking, signaling, sync points, etc. Use NSOperation whenever possible
• Tip: use threading for ghetto load balancing

TALK 4: Mastering OpenGL ES Part 1

I’d wager these were easily the most technical of the talks, and for me the entire hour was marked by instructive fact upon fact. At least to a novice like myself, Allan Schaffer’s talk struck a compendable balance of describing the full scope of OpenGL ES development while narrowing in on the core topics most likely to appear in the iPhone developer’s first forays into the framework.

• Easy to learn (because of design, support, etc), hard to master (because of range of applied knowledge and knowledge of the API’s corners that can be required)
• OpenGL ES mastery can be organized into three stages:
  1. 3D FFX programming, geometry
  2. hardware complexities, optimizations, data structures
  3. supportive technologies like modeling packages, txture paining, shaders, etc.
• OpenGL ES 1.1 vs. 2.0 – conditionally build for ES versions
• In the iPhone display system core animations acts as iPhone display manager and layers are the building blocks
• Understanding layering, CALayer and CAEAGLLayer, and how layers are animated and composited atop other layers, is fundamental to ES development
• Test with Animation Instruments to flash updated layers and determine how to best optimize performance based on compositing views
• Avoid pitfalls in loops with NSTimer by using CADisplayLink instead
• Optimize render loop by limiting frame rate and drawing on demand
• Xcode OpenGL ES template contains defensive code that is redundant if you’re not using multiple contexts and color buffers and such
• Build against ARM based on whether you need floating point maths or not
• Invest time in reading chipset specs, and the OpenGL ES specs in full

Talk 5: Testing and Debugging

The average iPhone application isn’t known for stability, and this appeared to be one of the most popular talks. I assume most developers attended already understanding the bulk of the material but thinking that even if they gleaned only one meaningful insight or tip the talk would be worth it.

That was my reasoning anyway, but it turned out that the very nature of having the full debugging and QA cycle explained by an Apple developer was reassuring and instructive, and cast some much-appreciated context to the regularly painful process and somewhat disconnected documentation. I didn’t take many notes for this reason, though I’d recommend the talk to others attending the World Tour simply for its walkthough value.

• Beta Testing – the full process of creating a build for beta testing was covered and there don’t appear to be any special steps or tricks on top of what’s commonly known
• Make sure to get crash logs from testers; the logs can be symbolicated by organizer effectively providing you with a backtrace of the crash
• The three most common types of crashes are: low memory, application errors, and timeouts
• iTune Connect allows you to see crash logs submitted by customers to be the App Store
• Springboard will always be shown in the logs to consume the most memory, but that’s just a representation of your app

TALK 6: Performance

This turned out to be my favorite talk of the conference. There was a tremendous amount of material covered so the pace was galloping and, as my friend Arthur observed, although it was the end of a tiring day we left energized and awoken. It’s fitting anyway for a talk on performance to speed along at a hurried clip. Of all the talks this was also the one that made me most want to get back into my code to refactor suspected mistakes.

• Use shark and instruments for profiling speed
• Memory concerns are fine to test in the simulator
• But timing or GFX or any hardware involvement should be tested on a device, not only the simulator
• Drawing optimizations
  • call setNeedsDispaly
  • check the rectangle passed to drawRect
  • mark views as opaque
  • invalidate timer before creating new timer
  • use PNG files as preferred image type
• ScrollViews
  • use opaque views
  • avoid allocating views during scrolling because allocating views is expensive
  • reuse table cells
  • collapse cell view hierarchy with lots of views, turning a parent uiview with many subviews into one big view with no subviews and use custom drawing routines for top performance
• Application launch
  • consider user’s immediate needs and load to that
  • make app launch and quit fast
  • load data lazily
  • use small nib for initial UI that is presented to the user
  • don’t perform network operations or expensive operations in ApplicationDidFinisLaunching
• Memory usage
  • use thumb if possible (floats), thumb 2 / arm if not
  • smaller executables (not bundles) make a difference to launch time since the app exe is loaded to memory
• Static memory
  • disable in compiler options
    • avoid c++ exceptions
    • avoid runtime type identification (RTTI)
  • prefer direct allocation over convenience methods
  • release directly over autorelease
  • declare properties as nonatomic
  • image and layers might themselves be small, but could have huge backing store
  • every uiview has a CALayer backing it
• Dynamic memory
  • 4b of data per pixel, RGBA, so big images have exponentially worse performance when they must be decompressed
  • Load UIImages with imageNamed for small, frequently used images; the method is also used by initWithNibName, and automatically caches uncompressed images
  • Load UIImages with initWithData or initWithDataOfMappedFile for large files, and release such images on memory warnings
  • Load UIImages with initWithContentsOfFile for all other (normal) circumstances
  • Use NSAutoReleasePool, especially in loops

Technical Q&A

As a final note, throughout the day those speakers who weren’t presenting at the moment were available for one-on-one Q&A and code review. I managed to grab a slot in order to pose a question that has recently demanded my attention: how, when using a UIScrollView, and zooming in, scrolling to a corner, and zooming back out, can you prevent artificial margins appearing on two edges of the contents?

The answer: you can’t. However, it’s known, noted, and the SDK team would like to fix the problem. Nobody there thinks this is an acceptable UI design. :)

]]> http://www.travisdunn.com/iphone-tech-talk-world-tour-2009-hamburg/feed 1 http://www.travisdunn.com/how-high-quality-code-is-like-the-most-profound-science http://www.travisdunn.com/how-high-quality-code-is-like-the-most-profound-science#comments Fri, 23 Oct 2009 15:37:35 +0000 Travis http://www.travisdunn.com/?p=934 Profound science isn’t merely useful, fundamental, accurate, or informative. Science that isn’t profound is still great and necessary, but profound science is a term I would reserve for science that has a high explanatory power with only a small number of postulates. Forceful examples include, say, Evolution, or Germ Theory. Such theories tend to be elegant and to some degree rely on emergence to account for a wide range of nature’s facts. They are simple and cut to the heart of the matter, but to take the example of evolution, allow a layman to understand the development of something as complex as the human brain.

So what *does* it mean to explain something, and what’s a postulate? How is it possible to compare scientific theory to something as different as software engineering using those terms?

 


Something About Abstractions

 

It’s ok to share abstractions because science already does this, using a common language and set of problem solving strategies despite the vast differences between bodies of science and their practices. And unlike fields which misappropriate the mantel of science, software engineering is actually a good candidate for the analytical power of scientific method no less than it is at demonstrating the more aesthetic, ineffable, and universal value which the most profound science carries.

The leaky abstraction pours from the fact that one discipline is observing the world while the other is creating it. Yet because science is a creative endeavor whose models will always be approximations put into play to some extent by way of someone’s chosen metaphors, there is important overlap with what’s done to create software systems that are modeling facts and processes with an attendant and vigorous disdain for falsehood and unpredictability.

 


The Sign of Few Postulates

 

Preamble aside, first consider profound science as a model of simplicity, holding few postulates in return for powerful explanatory power. Postulates can stand at different levels of abstraction depending on the problem they address. The postulates for describing the theory of evolution are categorically different than Koch’s postulates about bacteria, but they both serve the function of describing and testing a range of natural phenomenon in a very fundamental way, and only a handful of such postulates are needed to drive the ideas behind them.

In software engineering, this means no code duplication, the implicit or explicit presence of design patterns appropriate to the problem at hand, possibly but certainly not necessarily metaprogramming, self-documenting code, high expressiveness, loose coupling, emergent design and friendliness to the inclusion of new features (good theories will underpin others), and a strong emphasis on testability on a code level and falsifiability on a user experience level. All recognized signs of code quality, and what they tend to have in common is the reduction and simplification of complexity. And this is why I compare it to “a small number of postulates”: because software that manages tremendous complexity with minimal code is profound.

It’s probably not possible and certainly not necessary to achieve this level of profundity for most software, just as most science is predicated on dense silos of knowledge or seems hackish and incomplete despite its utility. But since we’re talking about how truly profound and elegant scientific theory relates to ideals of code quality, these rare insights into the universe are an appropriate analogous goal.

 


The Sign of Explanatory Power

 

The second requirement of scientific profundity is high explanatory power. In software engineering, this doesn’t become a matter of features but rather how well the code explains itself both to humans and machines. It’s hard not to equivocate here a little for the sake of comparison, but I imagine that for the machine side of the picture explanation means bug free code, impeccably balanced responsibilities throughout the codebase, defensively programmed, transactional and robust, and enough flexibility to permit feature growth and further layering as necessary.

What this really comes down to is internal coherence, stability, and interoperability. These are the qualities which allow software to, essentially, compute effectively. The TeX typesetting system is an example of software that “explains itself” extremely well on these counts, and I’m sure you can think of others yourself closer to your own work.

In addition, I think there’s also an element of ambition or grandiosity that factors into view; because science is describing the world its products already have a high minimum utility, and its biggest ideas reverberate down through the many different branches. Software development is less likely to produce, say, memcached, as it is to produce yet another CMS, and no matter how elegant that CMS it still probably won’t strike many as profound because the problems it solves are comparatively trivial. This isn’t to prefer software that’s more ambitious, however that which *is* has greater opportunity to aspire and reach the ubiquity and elegance found in striking scientific theories. In other words, the larger the problem, the greater the range of solutions that address themselves to it, and the greater the potential (or sometimes even necessity) for genius on the elegant end of things. Indeed, code we admire is rarely a Wordpress clone.

 


The Sign of Human Understanding

 

For high quality code to explain itself to humans, we require that it be maintainable, and as self-explanatory and approachable as possible, that it be intelligently-structured and organized with an almost alarming insight into how humans read codebases. This level of clarity comes from recognized best practices including self-documenting code, test driven development, strict separation of concerns, descriptive naming, DRY code, convention over configuration, and unswerving consistency in style, idioms, and design. These are the features of code that make it real and appreciable, not just a platonic exercise in machine efficiency.

The most profound science seems to rest on only a few premises around a key insight which seems obvious only in hindsight. Most science, however, is intricate and specialist, built up through operational, real-world practice and cumulative improvements to the central postulates. To understand the beauty behind such complex systems obliges a deep study of the material, and when understanding does come it is more by tenacity and mental fortitude that from the lucidity of the system design. High quality code and profound science provide answers to intricate problems with minimum dependency on related knowledge. Technical sophistication is often helpful and frequently necessary, but if humanity cannot efficiently put it to use then it remains a theoretical curiosity, waiting for the day when human minds and tools catch up to the appropriate level of abstraction.

Code that communicates effectively with machines but leaves most humans perplexed and unproductive reminds me of nothing so much as String Theory, packed with information and ideas and explanations but ultimately unsuitable for the environment in which we practice science today and the tools by which we do it. Also remarkable is that while the idea behind String Theory presents itself as simple enough, it turns out to be a useless metaphor when it comes to making predictions or manipulating physics somehow. Contrast this to scientific theories which seem simple, like Evolution, and actually are! Complexity often tries to hide behind the guise of simplicity, which is why profound science is so rare, or for instance, why so many APIs only seem to add another layer of sediment to dig through instead of lightening the load.

This also provides a clue as to why we’re not all programming in OCaml and Haskell despite their expressive power, or Fortran for that matter with a rich history of academia, but why something like Rails (almost a grand unified theory of web development) feels revolutionary and intuitive. To an extent, high quality code is like a domain specific language in the way that science builds itself through terminology and idiom. With the most profound science, these affordances become undeniable facets of the science and it becomes impossible to imagine understanding the problem domain without their linguistic and conceptual buttressing.

 


Information Itself

 

In the end, I’m not just arguing for the virtues of, say, simplicity or explanatory power, or really arguing much at all. I think what’s at discussion here is a set of heuristics for describing high quality code and the dramatic-sounding profound science, and whether these heuristics stretch from applied, natural science to computer science, or whether they are different things entirely. Sometimes these heuristics are virtues on a conditional basis, and some are sufficient but not necessary for excellence and profundity. Much science is done with impartial understanding and many codebases are good enough. Trying to consider only the truly exemplary cases, it is easier to focus on a set of best practices for either describing a world or building one yourself.

]]> http://www.travisdunn.com/how-high-quality-code-is-like-the-most-profound-science/feed 0 http://www.travisdunn.com/tools-of-the-trade-2009 http://www.travisdunn.com/tools-of-the-trade-2009#comments Tue, 13 Oct 2009 11:44:10 +0000 Travis http://www.travisdunn.com/?p=898 annual roundup of development tools, prompting Ruby Inside's Peter Cooper to issue a call for field reports from the rest of the Rubyist operatives out there. Here's my contribution to this reasonable meme. ]]> Mike Gunderloy posted his annual roundup of development tools, prompting Ruby Inside’s Peter Cooper to issue a call for field reports from the rest of the Rubyist operatives out there. Here’s my contribution to this reasonable meme.

Hardware

13″ 4GB Macbook Pro, circa Oct 2009 – running Snow Leopard and Windows 7, this aluminum savior is the anointed godhead of my development world.

17″ SAGER NP9262 (Clevo D901C) – the Apollo to the Macbook’s Adonis, this serves as my “power incarnate” machine. It wears Windows 7 handsomely, and will happily execute any resource intensive tasks I send to its gallows.

Dell 24″ Widescreen Monitor – Has saved more alt/tab keys than I care to calculate.

Mobile Edge Alienware Deluxe Backpack – it took a lot of restraint to put down my loathing for the garish-boutique-markup-vendor of a company and pick up their product, but Alienware carries one of the nicest laptop bags for bending spacetime to accommodate my 17″ Sager, complete with a bivouac’s worth of pouches and harnesses.

Dell XPS M170 – a venerable hero of bygone days, XPS remains in active service running Windows XP SP3 to surprisingly good effect. Trustworthy and redoubtable, measured as the balance of power and portability, and bearing a warranty that allows me to summon field medics!

24″ iMac – Media and not much else. Media and testing.

Backups

External 1TB Seagate drives – Handles everything from automated backups to disc images to source control. Almost as reassuring as RAID, with a bit more administrative overhead.

Various cloud-hosted SVN/Git repositories – Source control repositories are in my opinion the most natural location to “backup” and “restore” from, be it locally or in magical clouds dappled with unicorn glitter.

Synch between machines – An informal but nonetheless practical backup that comes as a consequence of frequently switching computers.

Software

Firefox – I don’t think I use as many FF plugins as most developers, but those I do I find to be indispensible.

• FireBug – Especially with all the Javascript development I’ve been doing in the last year, FireBug continues to reaffirm itself as one of the most important tools at a web developer’s disposal, and has attained a damn-near-ubiquitous presence in our community.
• Adblock Plus –It turns out that nobody wants to look at ads, no matter how important they are to a stranger’s business model.
• ColorZilla – Pure convenience plugin for ganking color schemes from attractive pages.
• CSSValidator – First step in CSS bug hunting, conveniently in plugin form.
• PageValidator – Another convenience plugin, helps with developing on FF and testing outwards.
• JSONView – Beautifully formatted JSON output a la the colored, indented XML we’re accustomed to.
• FireFTP – Integrated FTP for convenience, though I usually run FileZilla.
• YSlow – I can guess a site’s YSlow score in my head with reliable accuracy now, but it’s still an effective sanity check.
• Greasemonkey – Testing in the browser is *painful* and Greasemonkey eases this pain.

XCode – Getting better with every release, and the 10.6 build made some huge improvements.

Visual Studio 2008 – I don’t do enough .NET work these days to upgrade to 2010 yet, but VS remains my favorite IDE on account of its richness and excellent debugger. I still open it on a weekly basis for the Javascript debugger alone.

NetBeans – Probably the most used and abused software on my system after the browsers, NetBeans is a like a whole pantheon of gods for platforms I’m working with and has rightfully become my daily place of worship.

TextMate – A solid “DE”, it’s proven itself quite serviceable for Rails development with a earnest, supportive community striving to ensure, say, that we never run out of attractive color coded themes.

Mac Terminal– CLI power is liberating and arcane and productive like six days of God!

Photoshop CS4 – as only an amateur digital artist, I gravitate to Photoshop not for its power but because of the wealth of instructional information available. I started using Photoshop 4 in high school and the mostly awful Adobe has kept me as an impressionable customer since then.

Paint.NET/GIMP – Perfectly serviceable alternatives to Photoshop that I’m starting to come around to more and more. My GFX program of choice now depends on whatever computer I happen to be using.

MS Excel – The best software ever published by Microsoft and consummate spreadsheet tool. I use it daily in one sundry capacity or another.

Cygwin – For terminal goodness on Windows.

HeidiSQL – Stable, quick, lightweight database interface that just works and never hangs.

FileZilla – I’ve been using this for longer than I can remember for all my FTP transferring needs. If it’s not the best of breed, I wouldn’t know because I’ve never had a complaint that pushed me toward its rivals.

Git/msysGit – The DVCS of the gods; and mortals too, since this is probably one of the biggest software influences on how I work that I’ve adopted in the last few years.

SVN/Tortoise – And yet I also maintain a lot of older and perfectly operable Subversion repos, for which Tortoise is winning interface, though I find myself using SVN more for document management these days than code versioning.

TiddlyWiki – A potent cocktail of brain map, getting things done, project management, scratch paper, and other assorted miscellany that I’ve tried everything from MS Notes to .txt files to manage. TiddlyWiki is my ideal implementation of this bizarre, nebulous workspace.

KeePass – Everyone has a password manager, and KeePass is ever-sagacious gatekeeper to whom I entrust the keys to my world.

Truecrypt – Excellent security, and comforting fixture of my life the more and more I find myself traveling abroad.

PuTTY – For when I must adventure into the frightful lands of Telnet.

Growl – Eternally straddling that line between informative and intrusive.

Jing/Camtasia – For recording demos, screencasts, tutorials, whatever.

Adium/Digsby – Covers 99% of my communication needs.

Skype – And of course, Skype is the other 1%.

Hosting

Dreamhost – A compelling balance between affordability and “unterrible” support, even if the servers are habitually slow. Serves this blog and some other middle-ground needs of mine.

1and1 – Still hosting here due the uncompromising mediocrity of a company whose servers have never been worse or better than “okay”.

Pair.com – Most responsive technical support I’ve ever received from a hosting company.

Heroku – I’ve taken to pushing all new Rails applications I’m building over to heroku, both professional and personal. So far I’ve been very, very, very happy with everything from one-click deployments to their knowledgeable staff.

]]> http://www.travisdunn.com/tools-of-the-trade-2009/feed 0 http://www.travisdunn.com/web-service-api-design-by-example http://www.travisdunn.com/web-service-api-design-by-example#comments Wed, 07 Oct 2009 18:03:56 +0000 Travis http://www.travisdunn.com/?p=835 API design is one of the more important skills possessed by web developers today. The reason behind this fact is that web applications are increasingly unable to live in isolation while at the same time providing the scope of features and web awareness users have come to expect. Developing for the web means, to a greater or lesser degree, being a productive citizen in a kingdom of online data exchange; and whether by formal engineering or organic growth, this means building an API.

But API design isn’t limited to pursuing the affable integration promises of the open web. Understanding the power of an API in relation to application design is just as valuable to business needs as sharing data across services is to user desires. The power, in fact, stems from the same source as every other factor in systems design: managing complexity.

Unless you’re writing a Turing Complete API then your guiding objectives will be to simplify the intricacies of your application down to a suitable input/output abstraction, and describe the application’s behavior with as natural and predictable language as possible. The API is a white box with many different black boxes inside. Its design should generally represent a boundary point after which any further encapsulation of logic would require unproven assumptions, or else seriously violate the separation of concerns, and a boundary point before which any more flexibility and power requires special operating knowledge of the system because the API is too dense to be self-descriptive.

This is a razor-fine line and easy to slip from when moving within the system, but an API that’s clear and approachable to strangers serves in an equally valuable capacity at documenting behavior and intent. In the same way that TDD promotes the ancillary yet no less important benefit of forcing the developer to conceive of their code’s structure, methods, organization, etc. in terms of real-world usage, an API can also provide a sort of blueprint allowing for a theoretical rehearsal of the design impossible with strict bottom-up development.

None of these notions are particularly controversial or open to much debate; the tension is drawn between the gap of theory and practice, and for that I want to look at some examples from some of today’s prevailing web services. Reflecting on the conclusions reached by web leaders should provide us with insight into our own design efforts, and read the collective pulse of the open web.

Twitter

http://apiwiki.twitter.com

Positive: Twitter has become the gold standard in API adoption among the developer community, and much of this owes to a lucid API design. The organization of methods under loose “resource” groupings is easy to understand, and the individual method documentation is clean, forthright, and contains exactly the information you would expect including usage examples, authentication details, parameter constraints, response data, and more. What’s more, you can usually expect the resources to answer in XML, JSON, RSS, and Atom formats, another area Twitter stands out.

The documents do an excellent job of providing implementation these details, alongside top-level summaries of the general API design and conventions.

Twitter’s greatest accomplishment, though, is managing information overload from the potential expressiveness of the system. To point: you can almost immediately write code to begin talking with the API after reading only a few pages of documentation, and that’s as good a litmus test as any.

Negative: There’s not much to dislike about Twitter’s API and documentation, but one uncomfortable area is the quasi-RESTful model it implements. While the resource structure is clear, Twitter’s naming conventions are arbitrary and depend on the developer’s learning custom vocabulary for utility methods. This is a challenge failed by most APIs, though, and while Twitter is exceptional in many positive ways, here the API is no exception.

 

Basecamp

http://developer.37signals.com/basecamp/

Positive: The Basecamp API and documentation matches the 37 Signals adherence to simplicity, and you can familiarize yourself with the whole system in short order. The introduction covers implementation details like status codes, content types, and file uploads. If there’s anything to like about the API, it’s that you can learn it over a cup coffee.

Negative: For all its virtues of simplicity, the API lacks the cohesion found, say, in the only slightly more verbose Twitter API. The resources are well-named but the URLs are subject to unguessable nesting and inconsistent patterns. Searching and filtering data is not easily done, and the usage notes for those few methods which permit manipulation are hastily explained. As far as formats, only XML is supported.

 

Facebook

http://wiki.developers.facebook.com/index.php/API

Positive: Facebook’s API sits at the opposite end of the design spectrum, with a rich, intricate framework behind it. The power of that framework and data stores gives the API its strength and more than justifies its complexity.

Facebook deals with this by progressive disclosure in the documentation, and a small ecosystem of sub-APIs for permissions, application authorization, database queries, a markup and widget language, and many things in between. If the learning curve is steep, the documentation does a respectable job of guiding the developer down through specific methods and use cases as needed, and everything is well-organized, indexed, and linked.

Negative: The downside of the breadth, depth, and power is obvious. To use the API you must essentially learn a new framework, along with its own pitfalls and nuances. The entire nature of the design revolves around specialist knowledge, with heavily parameterized methods and enough usage exceptions to make casual experimentation and rapid development less inviting than alternative APIs.

 

Flickr

http://www.flickr.com/services/api/

Positive: Flickr supports a tremendously flexible API with an impressive number of both response (REST,XML-RPC,SOAP, PHP, JSON) *and* request (REST,XML-RPC,SOAP) formats. The documentation is descriptive, consistent, and concise, and the brief overviews on dates, encoding, tags, urls, and suchlike make further explanation in the method unnecessary.

Like many APIs, Flickr’s authentication is the most complex area of the API, which Flickr eases with instructive guides to authenticating from the web, desktop, and mobile platforms. The method naming is sensible, if not intuitive, while the method grouping is generally both.

Negative: Between support for SOAP and RPC calls, and a prescriptive approach to method naming conventions, Flickr demands slightly more special understanding than we would prefer, but with this as its greatest deficiency I find it to be on the whole well designed.

 

Digg

http://apidoc.digg.com/

Positive: Unlike other APIs here, Digg is essentially an endpoint to a single resource: stories. The heavy parts of the API revolve around filtering the stories on multiple criteria, as can be seen from the route index. The API’s basic concepts are standard enough, and while Digg expects its consumers to cache and chain data requests to prevent system overload, the documentation clearly explains the request patterns intended for talking to the API with these constraints.

Data can be requested in a commendable variety of formats, from XML, JSON, Javscript, or serialized PHP. Each documented method also contains plenty of illustrative example response data.

Because of the focus on stories, there are fewer API methods and each method call can be customzied and purposed with a variety of optional arguments. The documentation systematically explains the exceptions and conditions under which parameters are used, and the design gives far more power to arguments than to routes, in other words more RPC than REST.

Negative: On the other hand, the argument-laden nature of the API methods require careful review and implementation, overhead that could have been avoided by consolidating the filtiering logic either in the documentation or the API itself. This also makes it difficult to grasp the full range of the API without serious review of all of the its corner cases.

The flood controls on API requests are explained well, but irritating to accommodate in contrast to something like Google Data which has a more passive approach to imposing usage restrictions on its consumers. Further requirements like, for example, a User Agent header, make Digg’s API feel less inviting and fault-tolerant than alternative designs.

 

eBay

http://developer.ebay.com/developercenter/rest/

Positive: eBay is firmly in the RPC design camp, and frankly, aside from desirable auction data, there’s not much to recommend the API. If the documentation seems exhaustive – and it most certainly is, see the guide to REST, for example – then it’s an honest emmisary of the beast of a system which sits behind an ostensibly friendly API frontend. Although there are detailed code samples and a development sandbox, these are more necessary complications than any kind of extra, facilitating support. The API does support XML, SOAP, Name Value, and JSON output, though, which makes sense beside the seeming design ambition of leaving no possibility unimplemented.

Negative: Challenges for the developer abound in the API. Issues in the documentation from PDF-only guides, broken hyperlinks, poor IA for a system large enough to clearly deserve it, inconsistent method implementation and naming schemes, duplication of functionality, you name it! If there’s a potential roadblock to eBay integration, you’re sure to find it somewhere in this API.

The documentation is a mix of structured, heavily formatted schema descriptions with confusing conventions on when to bold/italic, change header size, change fonts, etc., and writing that ranges from conversational to clinical in enough voices to give the impression of design by committee. The jargon required to follow the nine-plus API products (searching, shopping, matching, feedback, trading, etc, etc) is everything from dependency and monkey-patching, and nothing from an open, agnostic web. Individual method writeups are an embarrassment of riches with ample reference but no progressive disclosure and little indication as to why one thing is more important than another, or suddenly described at a different level of abstraction than the rest of the page, even digressing into legal or business discussion in the middle of a technical section.

Perhaps the most damning complaint is that there is no suitable top-down entry point for acquainting yourself with design of the API and the extent of its power, no way to understand the goals and constraints of the system or even a clear idea of what exactly it’s modeling.

 

Technorati

http://technorati.com/developers/api/

Positive: Technorati answers the same needs as Digg, but does so with a considerably more elegant (if a bit less flexible) API. In fact, it’s elegant enough that no introductory document is needed, and there are only a handful of methods you need to access its full functionality. Responses are formatted as XML or RSS, and further documentation is provided for setting up custom pings to the service.

Negative: Although the superficial depth of the API makes for swift development, API influence is largely relegated to reading, not manipulating, data. And while a simple system might otherwise lend itself to descriptive structure and resource names, Technorati is not much better at its taxonomy that much more complex APIs.

 

Google Data

http://code.google.com/apis/gdata/

Positive: The Google Data API is difficulty to appraise simply because it’s so diverse. Google Data imposes the governing design for dozens of Google services that each depart from, reduce, or extend the Base API to varying degress. While there is a solid conceptual overview, introductory video, and plenty of examples and framework-specific libraries, the price of admission to Google’s power is study and specialization.

In addition to the resources mentioned above, Google’s documentation acquits itself well in presenting information on the daunting scope of functionality and flexibility found in its APIs. Progressive disclosure, intuitive taxonomy of services, methods, and overall IA, and concise, consistently formatted documentation are the winning conditions that keep the API accessible and friendly.

Negative: It’s hard to fault google for complexity while understanding the design challenge, and especially in consideration of the fact that large but comparatively smaller APIs than Google (e.g. eBay) fail much more spectaularly at intelligble design and documentation.

 

Netflix

http://developer.netflix.com/docs

Positive: The Netflix API is very RESTful with a convincing explanation (and diagrams) behind how resources are organized and manipulated, and some clever tricks like an “expand” parameter for retrieving associated model data.

Documentation takes an instructional approach, walking through the various aspects of the API with perhaps too much depth at places, a distraction otherwise compensated for by the outstanding layout, formatting, example code, and succinct writing style. The extensive annotated screenshots are well chosen and never seem to clutter your search for information. A more formal reference for the API is available as well, where you’ll find the Netflix design to be quite respectful of RESTful principles. There’s even a lightweight Javascript API for basic Netflix actions.

In fact, the documentation is so excellent, if a little verbose, only because it reflects a tight, descriptive API design. In this case,I don’t mind the API writers erring on the side of explanation because it’s always clear how what you’re reading relates to the API as a whole.

Negative: Netflix stands out among rival APIs, both in thoughtful documentation and technical design. Perhaps its weakest point is the use of OAuth for authentication, considering the added complexity. XML is also the only supported format outside of their Javascript API.

 

]]> http://www.travisdunn.com/web-service-api-design-by-example/feed 2 http://www.travisdunn.com/programming-at-full-speed-accelerating-the-central-nervous-system-reducing-brain-resistance http://www.travisdunn.com/programming-at-full-speed-accelerating-the-central-nervous-system-reducing-brain-resistance#comments Thu, 24 Sep 2009 15:29:52 +0000 Travis http://www.travisdunn.com/?p=786 The winner of the Netflix million dollar prize contest was announced this month. The two finishers, BellKor and The Ensemble, submitted their final entries 20 and 4 minutes before the deadline, respectively, securing BellKor the win by a harrowing 16 minute difference. I can only imagine the feverish pandemonium that must have erupted from both teams as the appointed hour approached. They must have been hurridly iterating to the very end, and whether ultimately through personal heroism or resourceful team support, the victory blow was delivered by programmers who have no doubt brought intensity and speed into their skill sets as a decisive advantage.

It’s that speed which can be worth a million dollars, or at least perhaps, seek and destroy eleventh hour bugs, ship a feature that’s been dropped for time, or make weekend projects feasible. High level productivity gains come from engineering and design decisions and are sustained through appropriate project management. The subject has earned the thoughtful analysis of countless technologists and programmers, but it usually stops short of the visceral fact that the sheer intensity of relentless programming can – in brute, anarchic glory – make more of an impact at the end of the day than any defensive design and planning. Code must be written, and no architectural optimizations can abstract that away.

I don’t want to dovetail into a blissfully approving flight path of crunch times or task-mandates that doing it right now is more important than doing it right. But that’s no reason not to celebrate a corner skill in our profession which everyone seems to possess at a demonstrably different level. And that’s certainly no reason to avoid overexerting ourselves in exercise, given that once we’ve grown accustomed to a hurried pace it becomes easier to apply in everyday affairs, to enter rush mode at will, to let the mind drift to planning while the fingers type the work.

So what are some ways to become a faster programmer?

Programming Competitions

More of a strategy than a tactic, willfully committing yourself to short, intense programming sessions over the weekend where you’re galvanized by the thrill of competition and the taste of an immediate product has got to be one of the best (albeit unscientific) ways to improve your programming speed. It’s not so much about learning tricks or practice, but personally acquainting yourself with a philosophy of frantic, obsessive concentration on publishing a small deliverable.

The scope is about right for these competitions to allow for focused programming with little worry of feature creep, reevaluations of design as complexities are uncovered, or the many other thoughtful distractions which constitute the larger role of development.

Words per Minute

The core virtue of fast programmers is lightning typing speed. You can’t peck aloofly at the keyboard, but must violently hammer away as if zombies were attacking your office and your life depended on completing a block of code before the barricades break. Youthful vigor counts for a lot, but so does unrelenting discipline.

Snippets and Generators

Most IDEs now have tools for managing code snippets and/or powerful template generators. Identify the handful of code you’re repeating most often – say, accessor methods – and write a snippet for it. I’ve only found myself writing perhaps 2-5 snippets at most, almost always to make up for shortcomings in the syntax and idioms of the platform I’m working on.

Hotkeys and Text Expansion

Similarly, dedicate yourself to learning the hotkeys of the environments you’re working with; print up cheat sheets and forbid yourself from using the mouse to perform actions with a known hotkey. Embrace mouseless computing.

Text expansion/intellisense/code completion is a special subset of productivity located in the mouseless computing paradigm, and the quicker you can type through heavily parameterized function calls the further you’ve risen above the limitations of verbose languages, libraries, APIs.

Head Programming

The quickest way to program is to embark with firm goals and implementation plans, programming the project in your head before you ever touch the keyboard. Formal specs take too long and impulsive programming leads to wasteful back-stepping, so the idea is to develop a balanced mental tour that gives you just enough context and boundaries so that, at any given point as you code, you’ll know what precisely what the next step should be.

Sub-Machine Guns

Prolonged white-knuckled programming is an unsustainable weapon in the developer’s arsenal, and must be used properly. By properly I mean “like a sub-machine gun”: sustained fire in short, controlled bursts. With ass on seat and fingers on the keys, dump as much code as possible onto the screen, but stop periodically to cool down and re-aim. The pause is only to gather your resolve for another assault and it mustn’t last long, merely long enough to ensure that you’re hitting your target and to crack your knuckles.

Mock Code

Building and propelling momentum is at the heart of fast programming (and, for that matter, entering the fabled “zone”). Anything that kills this momentum, even as a necessary evil, should be avoided. If an implementation detail is threatening to arrest your speed, abstract the offending code and push if off into some stub to be revisited later, preferably while waiting for a compile or test suite to run.

Working code is paramount when you’re racing the clock, and if you can defer some unexpected analysis until later, so much the better. My assumption is that a mocked feature now with full supporting code is better than uniformly functional but incomplete code. Yes, even magic numbers are better than putting on the brakes.

Code on the Side

Every second is precious, and we regularly endure brief moments of inopportune downtime while we compile the code, deploy it, launch the environment, run tests, transfer files, and so on. Always keep some code on the side to jump to and from during these lags. It must, of course, be the sort of code amenable to quick modifications, and requiring only minimal effort to mentally reorientate to and resume. There are always edges of a project like this, however, and the trick is strategically saving them to fill in otherwise unproductive gaps.

]]> http://www.travisdunn.com/programming-at-full-speed-accelerating-the-central-nervous-system-reducing-brain-resistance/feed 4 http://www.travisdunn.com/named-branches-logic-to-the-word http://www.travisdunn.com/named-branches-logic-to-the-word#comments Thu, 23 Jul 2009 19:21:54 +0000 Travis http://www.travisdunn.com/?p=207 Comments and self-documenting code are like brandy and cigars, the first illuminating your source (meaning both the gentleman’s soul and the source code into which he pours it), and the second imparting a blazing instance of clarity where you can taste the meaning.



Adherents debating the styles travel parallel roads in the direction of improving maintainability, but take opposing paths (and tend to toss aspersions across the median). Comments depart from reality over time and are perhaps redundant by nature, while self-documenting code is a frequent vanity and incapable of reflecting the many levels of abstraction that constitute design. I think a good way of realistically traveling these issues is by practice, and naming your branch conditionals (the subject I raise this very moment!) is a modest but noble idiom suitable for any lounge in solitude or with a cordial in hand.

Branch conditionals are important thing to name right because they’re all but the core flow of your code and you’ll be reading them over and over again in the repetitive quest for understanding, and its more senile relative, recollection. Branch conditionals (usually) look like this:

If (x && (y = (d  ? a : b) || y < e.p() ) )
{
blah();
}
else if (t.F() && g == q[0])
{
meh();
}

A far more readable and self-documenting way to formulate the code would simply be:

var isThisThingAndAlsoSomethingElse = (y = (d  ? a : b) || y < e.p() );
var butThatCouldAlsoBe = t.F() && g == q[0];
If (isThisThingAndAlsoSomethingElse )
{
doThis();
}
else if (butThatCouldAlsoBe)
{
doThat();
}

I find the separation of the comparisons from their consequences to save hundreds of milimoments of thought when working with code. Like most advice, it’s quite simple, and nobody follows it. The highest value can come from small optimizations like this, and collectively, when I scroll through source code with a lot of named booleans I read it that much faster than short files with pithy dents of anonymous conditionals.

In fact, I find this simple idiom useful enough that if I were granted one wish about all the code I’m to read before I die, well, named branches would be the second after the simple demand for thoughtful, verbose variable names, of which named branches is a like subset to begin with so it’s reasonable several times over.

A fortunate byproduct this practice is that naming branch conditionals can sometimes be hard, a fact you should use as a chance to articulate your logic. Choosing a name can also be a useful secondary measure of code smell, or suggest method refactoring, or reveal problems with business logic, and what’s more it’s a further refinement in this world of programming where nouns and verbs are given descriptive titles yet filled with murky details.

So what you have is self-documenting code because it reads like a comment, and it must read like a comment in order to express a more or less complex branch conditional. At a higher level, idioms like this are showing up in a lot of other places like Domain-Specific Languages and advice on naming tests, which are arguably just a branch conditional at heart themselves. What that suggests to me is that it’s a useful detail for programmers to orientate to.

Benefits: readability; passive analytical tool; DRY.
Costs: verbose; antagonizes our instinct for quick and clever over clear.

]]> http://www.travisdunn.com/named-branches-logic-to-the-word/feed 2