Showing posts with label architecture. Show all posts
Showing posts with label architecture. Show all posts

15 August 2016

A 14-Point Framework for Evaluating Programming Libraries & APIs (Part 1)

Libraries, network-services, virtual machines, platforms and frameworks, all qualify under the umbrella term "API". Some are simply things to be lived with — if we develop Windows applications, if we write Android or iOS applications, then we're blessed or cursed with certain platform-level givens, and there's not a great deal we can do about them apart from, perhaps, wrapping them behind a facade layer that feels a bit "nicer" — that makes life a little easier for us as developers by providing abstractions that more closely match the abstractions defined in our own applications and hiding layers of complexity that must necessarily be handled, but are uninteresting or distracting from the goals for our own development.
Aside from those "givens" we are faced (almost daily) with choosing other utility libraries and services to make our own development faster, simpler, more reliable, more performant and less repetitive.
This then, brings us to the heart of my topic: What exactly is it that makes one programming interface "nicer" than another? What makes one library "better" than another? Is it the expressive power? How would we go about measuring that? Is it how quickly we can churn out useful code, working correctly? Does popularity and coolness matter? There has to be a better way to measure — if only in a fuzzy and inexact way — whether one library or REST service is better suited to our needs and wants than another, and whether using a particular library might be better or worse than writing our own.
In case it is not already clear, let me emphasize: There is no One True Best API for any given task. Every problem lives in a context — a set of forces pushing and pulling on the boundaries of the solution space, warping the texture of the implementation landscape. Costs, time, expertise and past experience, functional requirements, timing and reliability constraints and, not least, developers' penchant for playing with the newest, shiny technologies — their desire to learn and extend their mastery. So: each and every API we choose to employ (as opposed to those that are forced upon us whether we will or no) must be tested against the problems we are trying to solve and the constraints and forces acting upon us and our application. A particular library may be the "right" answer for one project, but be quite inappropriate for the next one. Our desire for "good architecture"[1] suggests that we should, at least, make those choices consciously and deliberately rather than blindly or reflexively.
In what follows, I suggest some ways we might pick apart the various dimensions we might choose to use in evaluating various competing APIs, identifying 14 dimensions that you might want to consider as evaluation metrics in choosing (or avoiding) an API.
I should emphasize that I consider APIs (along with programming languages, platforms and codebase-hygiene) as primarily a UX problem. These things are all first and foremost user-interfaces for us, as tool-manufacturing humans to use, misuse or abuse. The principal question is, "How likely is it that this tool (API) will lead us astray and into the murky swamp of technical-despair?" versus "To what degree will this tool allow us to write less code, more reliable code, more readable (comprehensible, therefore maintainable) code?"
[1] I refrain from trying to nail down just what constitutes "good architecture" and rely, here, on your own intuition and experience. Suffice to say that it extends well beyond the merely technical concerns and encompasses the human, social and business spheres, too.

1. Surface Area

How many types, methods, configuration items do you have to learn in order to use this thing?
This is not unrelated to the ideas of Function Points as a way to "size" software — it attempts to measure the number of inputs and outputs (since that's what types and configuration items are) and use-cases for those moving parts. The absolute number is not important, since different APIs address problems of many sizes and a wide range of complexity, but it can be useful in comparing APIs that purport to solve the same or similar problem-spaces.

2. Coverage

How much of the topic-area does an API address? Is that what you need?

Does the API do all that you expect it to do? Does it do way more than you need? If the API is functionally incomplete, you will find yourself writing supplementary code to make up its deficiencies. That may be acceptable, but it may spell trouble if the API in question is supposed to be solving some complex or difficult problem (e.g. crypto) but is not sufficiently complete.

The case where an API covers way more territory than we really need is a little more subtle. Given appropriate tooling (not always available in all toolchains or environments) this is not primarily a technical problem (of linking too much object code into an application codebase, resulting in codebase bloat) but a cognition problem. Every part of an API wants to put little hooks into our brains. They call out to us, crying, "Me, me. Pay attention to me!" and we truly cannot afford to give them that time or mental space. Take the Google Guava library (for Java.) I use it on almost every Java project I am part of. But I only make really heavy use of maybe two chunks of what it does — the Preconditions and some annotations (for adding contract-like guarantees to classes) and the Collections (particularly Immutable collections) classes. The rest of the library is mostly surplus cognitive baggage most of the time. I'd be better off with it being in a separate library to be pulled in only when truly needed. Indeed, I have seen projects that end up with as many as three separate definitions of methods like isNullOrEmpty(aString) and checkNotNull(anObject) simply because developers did not want to pull in all of the Guava library in the early stages of their project, then acquired another instance of those methods because some other third-party library made those definitions, and, at the end of the day, they ended up using the Guava library anyway for other reasons. What a mess.

3. Composability

How well does this API play with other libraries and tools?
If an API works in terms of platform-compatible types, it is much more likely to play well with other APIs. If it insists upon introducing and using only its own types, it will be much more difficult for us to force it to play well with the other libraries in our armory — we are sure to find ourselves writing endless boilerplate code converting between custom datatypes. And unit tests for that code. Or not, so hurting our code coverage metrics and creating emotions of despondency and discouragement because clearly we suck at doing The Right Stuff.

4. Modularity

How easily can we break this library into pieces so that we can use just the bits we need?
This is (again) about reducing cognitive load. Does a library allow us to just pick and choose the bits that suit us well, leaving the remainder strictly alone, or does it force us to schlepp in all sorts of sundry other parts of the library that do not touch on the problem we're solving. Some frameworks tend to be really bad at this.

5. Openness

How much is this API a black-box?
Can you tweak the under-the-hood stuff if when you need to without delving into the twisty, slippery innards of the implementation? This is simply the Open-Closed Principle in its essence.

6. Opacity

How well does an API hide the details and complexities of the problem-space? A well-thought-out API will shield us (to an appropriate degree) from the concepts and particularities of the underlying domain it deals with, allowing us to work with concepts the ought to be much closer to our own, more familiar application domain. The types and operations exposed at the surface of the API should reflect something more amenable to adaptation to our own conceptual framework than the underlying problem that it hides and manages.

If a library is not making stuff simpler for us, why bother using it? Does it provide a facade that makes sense in the context of the problem your application is attempting to solve?

7. Accessibility

Can you learn just a little bit of the library and be useful (Vertx), or do you need to learn the whole damn thing before you can (safely) use any of it? (Git)

Accessibility is one of the more important dimensions for thinking about APIs because it means we can tackle the (sometimes daunting) task of learning to use a library truly effectively in little bites, and each little bite that we can chew and swallow gives us an ever-increasing confidence in the library, and an ever-increasing confidence in our own abilities to put it to good use.

I shall continue with the remaining seven dimensions in a follow-up post in a couple of days. This thing is already too long for Internet-attention-spans as it is.

06 February 2012

Work Wanted

This is a small call for help. I am looking for work, and need your help.

Contract or permanent. Preferably (but not exclusively or even at all) telecommute. I can code, design, architect software, consult in any of these (and dev process/team issues) and teach a variety of Java, OO Design and web development topics, and would be happy to do any/all of these. I additionally have some experience doing system administration work. I work in Linux/Unix environments and know next-to-nothing about Windows.

I've done web stuff, and loads of backend "heavy lifting" coding where reliability, scalability, etc. are important. I am not good at quick'n'dirty. Skeptical of the value of buzzwords and big-arse frameworks.

Check out my "business" website for more details about me and what I've done in the past.

R (as they say) "highly neg".

If you have anything suitable, or know of anything that fits, please drop me a line.

I will be in Cape Town and environs next week, so an ideal time to get together and chat about possibilities and opportunities.

11 November 2011

Android Nails Sandboxing

So I'm learning to programme the Android platform. Despite constantly typing it as "Androind" finding programming fun again after many years of regarding it as somewhere between tiresome drudgery and only mildly interesting in sporadic parts.

It's early days, yet, but I do think that Android's architects had one flash of brilliant insight: Using Unix user and group permissions to sandbox applications. Brilliant! We've had this mechanism since forever, and let's be honest, it's never been all that useful except in the very early years of Unix when we actually did have to put multiple users on a single computer. And even then, most users didn't understand it. Questions about umask and file permissions are among the commonest of Unix confusions I've run across for the past 25-odd years.

Warping the idea to mean that every application is a unique user is a flash of inspiration.

22 August 2008

Courseware: The Next Step

Just received my Instructor's Manual (only a week late!) for Sun's SL-425 "Architecting and Designing J2EE Applications"1 and I'm very happy to see that it is basically the same course as the old "Architecture and Design" course I taught several times lo' those many years ago when I was so frequently on my feet as "Herr Instructor".

This is easily the best2 course I ever "taught"! It is aimed a senior, experienced designers and developers3, and confronts head-on the sticky few-good-answers stuff, the ill-defined and the fuzzy grey areas. I have always run the course in a round-table "workshop" format. When you get 8 or 10 senior developers into a room, each with a decade or two of experience, you're not going to be their Teacher. And you sure as hell better not have a tender ego. "I don't know" is a frequent answer. The job is much more one of facilitation: Keeping discussion on-track, drawing quieter participants into the discussion, acknowledging expertise and encouraging people to share their (often vast!) experience. I found it hugely enjoyable to engage with seriously expert people, and to facilitate drawing out their expertise. And I learned a lot!

It has been a very long time that I have wanted to run this course again, so I'm looking forward to it hugely!

So: I have a couple of weeks to catch-up on the changes since last it taught facilitated this course. Mainly the technology has caught up with the tech: Where there was only CORBA or RMI a decade ago, there are now a host of J2EE technologies, and the course now includes them. Where a decade ago the whole idea of enterprise-architecture patterns was pretty new and unheard-of, now there's the J2EE Blueprints Catalogue (even if those yanks can't spell "Catalogue"!)

Of course I'll probably be unable to resist the temptation fo slipping in a few sly teasers about Jini and Javaspaces -- but Hey! Sun seem to encourage instructors to go beyond the boundaries of the course material, and encourage us to bring our own experience into the classroom. Or workshop in this case.

I am still thinking about floating my own version of this course, perhaps a little less attached to Java tech, so that more people might engage. The absolutely best runs of the course were when we had many people from different organisations and backgrounds. Cross-pollination really works. Ask plants!
[1] Is there such a word as "Architecting"? My spelling-chequer doesn't seam to think sew.

[2] "Best" from my point of view, anyway. Though, I can honestly report that every participant I've ever had on this course reported exactly the same sentiment!

[3] I don't believe the term/job-title "Architect" had any currency back then. Whilst it had certainly been invented4 it was certainly not popular. In fact there still was no such Job Title as "Software Designer" back then. My boss had to invent it for me!

[4] I believe that I was one of the (probably many) inventors of "Software Architect"a s a job title. Certainly not unique in that, though! Back in 1989 a technical career-path looked much like "Junior Programmer - Programmer - SeniorProgramer - Junior Systems Analyst - Systems Analyst - Senior Systems Analyst - Business Analyst..." I rejected the whole deal5 stating "Analysis is The Art of Taking Things Apart. I don't want to do that. I want to put things together, and that's called Design (and, at the high-end, Architecture)."

[5] ... in a bi-annual merit-assessment that became (in)famous as the one where I told my Manager, "If you want loyalty, get a dog! This is a business relationship; didn't you understand that?" Needless to say I got no increase that year. ;-)

15 December 2007

Quartz Crystal

A very trying couple of days...  Faced with a job that cries out for a decent scheduler (polling feeds), I turned to OpenSymphony's Quartz.  I mean, the ads look so good: Robustness, recoverability, scalability, blah, blah.

First hint of warning I should have paid attention to was a couple of developers' names that I long associate with Doomed Pieces of Shit.  But it all still looked so good.  Until I got closer to the code.  Quartz?  Quartz Crystals for accuracy?  More like Crystal Meth!  Documented methods that mysterious fail to exist.  Examples that aren't.  I thought the JavaDoc got generated from the source, no?  I guess we have here the penetrating stench of Configuration Mismanagement.

Then you enter a twisty little maze of undocumented dependencies.  You will use Commons Logging.  You will use a bunch of J2EE stuff, even though you application is a simple standalone with no hint of J2EE awfulness in sight.

No.  After a day or so of hacking at this steaming turdpile my brain feels like so much oatmeal porridge that I can't even work even work up enough bile for a decently vitriolic blog post.  For me, one of the surest signs of a dying opensource project is when their wikis and forums are filled with spam because nobody can be bothered to disallow Guest users from posting; when the version-control system shows six checkins in the past six weeks.

I'm outa here in favour of Doug Lea's concurrency stuff. What a pleasure by contrast.  I'll live without clustering for now...

30 July 2006

Microsoft playing catchup to Jini?

I just saw The Ray Ozzie Experience and almost ROTFL.
"A world of many devices, all connected and managed by the Web".
Isn't this what Scott McNealy was telling us like eight years ago? Remember "WebTone"? Welcome to the party, Ray Ozzie.  Sorry that you're so late! M'afraid the beer's justabout finished...

Isn't this exactly what Jini was designed for? (And I'd infinitely sooner bet my life on technology as mature and carefully designed as Jini than on anything MS is ever likely to come up with.)
Related Posts Plugin for WordPress, Blogger...