Anyone have the first clue as to why Facebook’s developer documentation sucks so hard?

I was developing a simple Facebook application for one of my company’s clients that required me to update a user’s status via a scheduled background process. The developer documentation lead me down all kinds of paths by referencing infinite session keys and the “keep me logged in” check box. So I scoured the internets for some examples, only to find that there aren’t many. All these claims that bajillions of people are creating Facebook apps and not a single one of them that are updating a user’s status offline can document it? ARRRGGG!

So, here is what I hope will save someone else a ton of time – a real life, working code sample for updating a user’s Facebook status offline. Careful – make no sudden moves or you might scare this rare beast back into hiding.

Our app is requesting two extended permissions – “offline_access” and “status_update”. This is also using Elliot Haughin’s Facebook plugin for CodeIgniter. Elliot’s package includes an older version of the Facebook PHP Library, so I had to grab the latest version from Facebook and drop it in place. Other than that it was easy to integrate this into my app.

//http://wiki.developers.facebook.com/index.php/Users.hasAppPermission
//must be one of:
//   email, read_stream, publish_stream, offline_access, status_update, photo_upload,
//   create_event, rsvp_event, sms, video_upload, create_note, share_item
if( $this->facebook_connect->client->users_hasAppPermission("offline_access", $fbUID) &&
    $this->facebook_connect->client->users_hasAppPermission("status_update", $fbUID) ){
    $this->facebook_connect->client->users_setStatus("some status message", $fbUID);
}

Seriously, that’s it! All those posts, all that searching – for 3 lines of code! The key point that was conveniently left out of other articles is that there is no “session key” required now. Facebook is smart enough to know that the user granted the app permission for offline_access and status_update, so you only need to send the user’s Facebook ID. Moley.

Another annoyance. They make a big deal out of the fact that they provide a REST-ful interface, but none of the examples in their documentation show the format of the REST request (although they do at least provide the REST server URL and a handy hint to include the “Content-Type: application/x-www-form-urlencoded” header). Yes, I get it, you want me to use the PHP Library, which is nicely designed. But for quick and dirty testing I like to whip up some curl commands. If I don’t know how to format the XML I can’t easily do that. Bah!

I’m amazed at the amount of code that I see that contains uninitialized variables. I can’t think of a bigger bang-for-the-buck habit you can fall into than taking an extra 2 seconds to properly initialize whatever variable you’ve created. Look, I know a lot of ORM layers use NULL variables as a flag to insert/select/update null values. I get it. I don’t love it, but I get it. Other than that, I can’t think of a single reason to not initialize your variables. Unless you love NullPointerExceptions, or security exploits, or constantly having to check for null before you call a method on an object you just got back, or who know whatever else people have done to themselves because they were to lazy to add ” = 0;” after their variable declarations. Coding is hard enough as it is. This just makes it harder.

In an earlier post I referred to the tendency of a site’s home page to speak volumes about the character and and principles. I call this Psychotic Home Pager Design Syndrome. There are a couple of great examples of this, but the ones that stand out best to me are sites like GoDaddy.com, ESPN.com, and MLB.com. Imagine you are someone coming to the home page of one of those sites looking for a very specific product. Imagine trying to find that product in the mess of boxes and links and images and ads. It’s impossible.

One might argue that these companies have tons of products, and the home page reflects the need to have their most successful products featured and touted. Exactly. Having worked at MLB.com, I can tell you exactly how this happens. You have 2 distinct business units with shiny products that represent some business interest. You have 2 product managers who equate sales of their product with the size of their year end bonus. You have endless campaigning to have your product featured on the home page, where it will get the most traffic. You have exactly 1 CEO who doesn’t really want to have the product managers draw short straws because, afterall, it’s just pixels on a page. So the end result is a mish-mash of products and services that speaks more to the internal structure of the company than to usability.

Contrast this to a company that gets a lot of fanboys/good press – 37Signals. I won’t go into details here about my thoughts on the 37Signals hype (that should tell you enough), but for a company with a good smattering of products their home page is simple and usable. In the context of what we know of the internals of their company, this makes a ton of sense.

This article covering a talk by Rasmus Lerdorf on the issue of scaling PHP and PHP Frameworks is a couple of months old but keeps popping up on Delicious. There’s a lot to disagree with there, especially if you read through the comments by other people who were in the audience for the talk, but the thing that stood out for me benchmarking covered in the “Hello World” section.

Please please please tell me the reporter misunderstood Rasmus’ point, as some have suggested in the comments section. I can only hope Rasmus (who, btw, is a vocal member of the Nike+ Running community that I work on at R/GA and has written the SlowGeek site to improve on some features he felt we were lacking) would not make a big deal out of such a naive example. So you’re telling me that “Hello World” printed out directly from a PHP file is orders of magnitude quicker than “Hello World” printed out through a PHP Framework? Amazing. I will immediately concede that if your intention is to write and scale a “Hello World” application CodeIgniter or other PHP frameworks are not for you.

It’s like saying that it takes longer to get to the corner store if you take you helicopter as opposed to walking. Sure, you have to suit up, start up the rotors, take off, find a good landing spot, step over the dead bodies, etc. But that’s not practical is it? Either is a “Hello World” example.

Look, I’m perfectly willing to accept that CodeIgniter will be slower than a hand-crafted framework when all is said and done. That alone is the reason I don’t use any ORM in my code. It can’t possibly be faster. But for something at my scale it makes configuration, development, and maintenance very easy. And in the wise words of the fine developers at Coding Horror, programmers are expensive and hardware is cheap. To a certain scale, you can just throw hardware at your problem.

That said, I’m sure Rasmus understands that and the reporter took him out of context. Right….?

So right now I’m looking at a table that has at least 3 different columns that control whether the particular row is displayed on the front end. In some cases that’s unavoidable, but it has to be kept in check.

Maybe you can tell me what the difference is between the intent of these columns: status (e.g. pending, active, canceled) and should_display (0 or 1). In addition to that, there’s one part of the code that will ignore a record if one of the FK columns is null but will consider it if it’s non null.

This is madness. I now have to piece together which columns are significant to which consumers of the data. And then I have to figure out the magical combination of values to make the row appear on the front end. This leads me to some quick rules for database flags:

• Limit the number of display flags to as few as possible. I usually use a is_active or display_order column to determine whether the row should be retrieved. There will be cases where the row should be retrieved by one consumer and not another, but there should never be more than one column that does almost the same thing.
• Use descriptive column names. The ones above are too general. is_active tells me exactly what I need to know.
• You can use a nullable timestamp column to do both boolean checks and date-triggered checks. In other words, if the column is null it means the column is still valid. If it’s not null you have to check it against the current timestamp. This saves a duplicated column and is fairly easy to get across.

If there’s one concept I’ve fought my entire career it’s that there can be, or even should be, a way to make everything work “automagically”, a term the afflicted developers use lovingly. I recently christened this the “Magic Button Syndrome”.

Usually a bunch of fairly smart developers sit in a room and start dreaming of how a system might work. “We have to make sure we can easily modify the configuration,” one might say. “We should have a means to generate the configuration based on some other configuration file,” another might respond. “Let’s use annotations to make sure that the configurations stay in sync across versions,” someone else might suggest. Yet another person might think it’d be wonderfully cool if you could auto-inject annotations somehow.

Their triumphant moment comes when the CTO is standing over their shoulder screaming about something that needs to be fixed ASAP and they nonchallantly say, “Oh, I can fix that, one second.” They turn to their machines dramatically, edit one or two lines somewhere, smack the return key, twiddle their thumbs, reload the page, and then smile. “No big deal,” they’ll say with a smirk on their face. That’s it. That’s what they live for. They want that one Magic Button moment.

It sounds foolish, but there are plenty of developers like that out there. For these people, it makes perfect sense that if you can automate something little, automating something bigger containing tons of moving parts must be even better. Eventually the automation will reach singularity in the Magic Button.

The problem is that automation suffers from the same law of diminishing returns as does traveling at the speed of light. It takes an infinite amount of energy to accelerate a particle with any mass to the speed of light. In the same way, it takes an infinite amount of energy to create that Magic Button. Not that it stops people from trying. Sure, changing one of the thousands of options that are contained in a config file or database is easy. But if you’ve worked on systems like these you know that doing anything outside of the realm of what the system was designed to do is absolutely, unbearably painful. That Magic Button hides layers of abstraction upon abstraction upon abstraction. Just when you begin to understand what a peice of code does you realize you forgot what code is calling it. In the effort to make something of uber-value, no single component makes any sense.

You find it takes people months to really understand the system. Changes take weeks to test, and lead to reprecussions that no one really ever expected. Once all the original developers are gone everyone starts to realize the system needs to be redesigned. It’s become like the pyramids – beautiful, absolutely brilliantly designed, but a total mystery. This time we’ll do it differently. In Ruby maybe. And auto generate all the documentation using XML…

I decided to use CodeIgniter for a PHP project that I’m working on. CodeIgniter is an MVC framework, not too unlike CakePHP. At least I imagine they’re very similar, but I can’t say for sure as the reason I chose CodeIgniter over CakePHP was that the CakePHP documentation is a mess and I didn’t have time to wade through it. CodeIgniter has been fairly easy to work with so far. I’m sure there are tons of CodeIngiter reviews by developers like me out there, so I won’t bore you with that just yet (future post!).

This post is about Model-View-Controller (MVC) architecture. Like any developer, I’ve read countless retellings of why patterns and MVC are good for your code. True to form, I think those claims are overblown. I’ve worked with people that do everything “By the Book” and I’ve worked with people that hack everything together as best they can. Seeing both sides of it I honestly can’t say that one made my life any better than the other. Unstructured code, if kept reigned in to some degree, can be incredibly flexible and allow you to be agile in the face of rapidly-changing priorities.

For instance, I’m not above having SQL statements in a JSP file. I don’t love it. I try to avoid it if it’s going to get messy. But I don’t think it’s something to be embarrassed about. I can’t tell you how many times I’ve been able to move a change out in minutes rather than weeks because I was able to tweak a query in the JSP. No, it’s not “By the Book”. But it works, and in the end that’s what you get paid for.

My general rule of thumb is that the closer to the end user your code is the more flexible it has to be. Consider the following range of technologies that flow from the user end to the server side: HTML/CSS, Javascript, PHP/Java/Ruby, PL/SQL, database schema. HTML needs to be more flexible than Java, which needs to be more flexible than the database schema. So for every 1000 times you tweak your HTML or CSS, you might need to make a couple of changes to your backend Java. Sounds reasonable.

So coming back to MVC, one thing I’ve never understood is why the controller is responsible for selecting which view is invoked. This seems fundamentally flawed to me. In a language like Java the controller is a servlet compiled into a jar file somewhere. To change the behavior of that file you have to go through an entire release process: change code, test, promote to QA, test, promote to production, test. At MLB, a change like that took about 2 weeks from start to finish. (Obviously the situation is a little different if you use PHP, which is why I’ve decided to use an MVC framework for the PHP project).

In essence, it’s like the backend developers are saying “Move aside HTML, let the big boys make the call. We know better which file should be displayed”. You know what, they don’t and they shouldn’t. Yes, I know about Front Controllers. Yawn. Yes, I know you could easily write the system such that the flow through the views is configured using XML so it can be changed on the fly, as they did at MLB. Snore. Don’t get me started on XML for configuration. These are all solutions in search of a problem. These things can be done, but no one has really ever convinced me that they need to be done. Agility requires simplicity. Simplicity can’t be configured with XML.

It seems like a long since I was the youngest guy in the office. Those days were pretty golden. The young turk is the one that everyone lives vicariously through. I remember recounting stupid drinking stories to a cube-full of older developers eager to relive their own youthful transgressions. The young turk can make mistakes that older guys would get reamed for. And he can get away with unsavory behavior because his unofficial responsibilities include comic relief. The young turk has it pretty good.

These days, I’m almost always one of the oldest guys on the team. At R/GA there are some team members about my age, give or take a year, but most of them are between 4 and 10 years younger. Of course, no one would be stupid enough to be caught arguing that age should imply much in terms of ability. The point is that I’ve spent a lot of time in the past couple of years wondering where all the old developers go. At R/GA there can’t be more than 5 developers (including the front-end guys) 35 and older. This is in a company with probably 150 or more tech people. At MLB I’d bet most of the tech group was under 32. With the exception of the CTO, I can’t think of anyone who would have been older than about 38. This is out of about 100 tech people. I have this fear that I’m going to just start melting away when I turn 38. Or worse – be forced to move into human resources. I mean, I know coding is a young man’s game, but this is absurd.

I suppose some become middle management, but since an organization might only need 1 or 2 managers for every 10 developers there are fewer of these to be found too. Lately I’ve been wondering if the older folk need something more stable and find themselves moving to investment banks. I can’t really say because I’ve avoided those kinds of jobs my whole career. Maybe they freelance, or start their own companies. Maybe they get fed up and go teach. Damned if I know. All I know is that it’s starting to freak me out a bit. How much longer until the developer police show up at my door and take me out to the shooting range? Come to think of it I’ve been hearing voices coming from my O’Reilly books – what if they’re really made out of ground-up developer parts? It’s starting to make a certain bit of sense.

My code is my house. I spend a lot of time in it. I fix it up, take care of it lovingly. I indent appropriately and actually spend time spacing out sections so they’re pleasing to the eye. I do this only partly because I’m obsessive compulsive. My greater motivation is that I really feel that these things matter.

Think about the word “code” for a minute. I love the word. I am a coder. I write code. What is code? Code is something that means something to the person that writes it, means something to some people/machines that read it, but means nothing to people who don’t know how to read it. Code is inherently cryptic. So the act of writing code is a struggle against entropy. Over time the code’s intent will change, its implementation will be less clear, or its documentation will drift out of sync with the actual representation.

As when you move into a house, code will never be as nice as it is on day one. Something breaks and you have to fix it quickly, leaving a hole in the wall. People come to visit and leave their shit around. Perfect code never stays perfect. So it’s critical that on day one the code is as clean and clear as it can be. And you should expect to do periodic improvements to keep entropy at bay.

Speaking practically, this implies a number of things. First and foremost, formatting matters. Spacing matters. These things help someone else determine the intention of the code you are writing. Related sections should be grouped together with spacing so someone reading knows what can be moved around and what should stay together. The goal is to make the code as pleasing to someone else’s eye as possible. We all know you are very clever, but a single line that chains together 50 method calls is impossible to decipher. Break it up and I’ll respect you more because you did it for me, not for you.

Everyone has a favorite format. The religious wars about curly braces probably consume half the storage space on slashdot’s servers. I’m not entirely above it – I’m infamous for reformatting code when I take control of it. But if I’m just visiting someone else’s code I have a strict policy that the code I write should be indistinguisable (as much as possible) from theirs. This means formatting it the way they do. Using the same naming conventions. Following their capitalization scheme. The point isn’t to show others how superior my formatting is. It’s to make sure that someone else reading the code doesn’t have an anuerism.

Slow week, so thought I’d vent. The top 3 things that seem like good ideas at the time:

1. Using IDs in WHERE clauses when a CHAR or VARCHAR column could be used. This is another of those pesky “proper design” practices. As a developer, you should always assume that a row’s ID can change at any time. This is most tempting when joining to lookup tables, where you think the IDs will never change. That might be true in the development environment, but maybe the IDs turn out to be different in the production environment for any number of reasons. All your SQL breaks. It’s always safer to use a unique identifying string value in joins where possible. And if your lookup tables weren’t designed with a unique key on a string column, you should create one. It’s much much safer to do:

   SELECT p.name FROM people p, groups g WHERE p.group_id = g.id AND g.name = ‘friends’

   than it is to do:

   SELECT p.name FROM people p WHERE p.group_id = 1

   At that rate, why have a lookup tables there in the first place? (No, I’m not really suggesting this, although I have worked on systems where this was commonplace).

2. Misuse/Overuse of IN clauses. When I’m writing ad-hoc queries I tend to throw around the IN clause liberally because it’s usually quicker than a join. In production code, you should severely restrict your use of it. For one, it’s not the most effiecient clause for the database to execute. For another, it’s error prone.Here’s the wrong way to use an IN clause:

   SELECT p.name FROM people p WHERE p.group_id in (SELECT id FROM groups WHERE strangers = ‘n’)

   I guess some developers have the impression that it’s easier for the DBMS to optimize that because it looks like 2 separate queries squashed together. In most non-trivial cases it’s not easier to optimize. Here’s the right way to use an IN clause:

   SELECT p.name FROM people p, groups g WHERE p.group_id = g.id AND g.strangers in (‘n’, ‘notsure’)

   In most correct uses, it could be conceptually replaced with one or more OR clauses. So lay off the IN clauses please.

3. SELECT * FROM …. queries. There is no reason to ever SELECT * from any table. No reason. It’s a lazy, horrible practice. Spend another 3 minutes and protect yourself from the bugs that will eventually arise when someone adds or modifies a column to that table. If you’re really too lazy to type out the column names, you can do something like this:

   SELECT column_name FROM user_tab_columns WHERE table_name = ‘MESSAGES’

   The table USER_TAB_COLUMNS is part of Oracle’s data dictionary, which I’m hoping to cover more in future posts. That’s just one way to be lazy and productive at the same time.