Use coding standards and best practices

Proper method names, argument names, argument types and return values are crucial to the mere mortals trying to use your API. Keep an eye on your naming schemes! Use the common denominator of data types when you can and create specialized value objects when necessary. This method signature might make perfect sense to you at a time of writing:

1

getCoords( arg1:*, arg2:*, ar3:*):Object

…but please clean that up when you release it to the general public! Answer me this: What kind of coordinates are we requesting? What kind of input is expected and what are their types? And what the hell does that generic return type contain exactly?? Might I suggest something like:

1

getCityCoordinates( region:String, country:String, city:String):Coordinates

You might think this kind of thing is trivial and basic. And it is, hence my bafflement when I read stuff like the first example in library released as the official API for one of the more common social media RIAs. You couldn’t imagine how many APIs out there break away from such common sense.

Clean up after yourself!

There are libraries out there without a single line terminated by a semi colon. As we know, the semis are optional, but they can cause the dreaded “internal build error/classes may not be nested” situation in Eclipse-based IDEs which usually eats up at least half a day of valuable time. I’ve had it happen to me, and needless to say I don’t consider semi colons to be optional. I use FDT to write my code and I have it set up to present me with an error whenever it comes across an unterminated line.

Other known culprits of internal build error are empty constructs like if-, for-, while and switch statements in addition to empty classes and interfaces. If there are incomplete sections in the API, pull them out and make sure the rest of the code doesn’t reference them.

Write proper ASDocs

How many libraries out there merely repeat the method signatures in the ASDocs? Then what’s the point? Most sane people use advances IDEs that will present ASDocs even inline with the code hinting, so make the most of it when the function and argument names cannot convey the full purpose of a property, event or method. To demonstrate, I will give an example from the ASDocs of my own logger utility, the Olog. I will not be humble in this case, because Olog’s ASDocs are in fact immaculate.

The main logic is spread across 10 classes, but there’s only two access points to the log console; the specialized event type and the Olog class itself. The Olog class serves a single purpose: It is the interface, the Application Programming Interface. It serves as the entry and exit point and the position of all the documentation. The core of the module is not as pretty, but that’s my problem. The Olog class consists of well named functions and getters and setters, all with comprehensive and highly cohesive ASDocs. In a sense you could say that this class’ primary purpose is to act as the black surface coating in the black box principle; it’s there to stop the reader from digging deeper, or should I say to make it totally unnecessary to dig deeper. Most of the methods have a single line in them, a call to another core method. This allows this class to focus on the task of providing decent documentation. The ASDocs are generated from this file.

This is a method from within the core of Olog:

1
2
3
4
5
6
7

internal static function newTimeMarker(name:String = null, origin:Object = null):int
{
	var n:String = (name) ? name : "Operation";
	var o:String = Otils.parseOrigin( origin );
	var t:int = getTimer( );
	return _runTimeMarkers.push( [n, t, o] ) - 1;
}

But from the outside of the box it appears like this:

1
2
3
4
5
6
7
8
9
10
11

/**
* Creates a timing marker that you can later complete by calling completeTimeMarker() to
* output the time in between.
* @param name String reference to use when the marker completes an results are displayed.
* @return An integer ID to use as argument when calling completeTimeMarker().
* @see completeTimeMarker()
*/
public static function newTimeMarker(name:String = null, origin:Object = null):int
{
	return Ocore.newTimeMarker( name , origin );
}

Thats a ratio of 5:2 of respectively documentation and actual code! By using the Olog class as a dedicated API layer, I’m able to use that class as both a source of proper ASDocs and a structural reference for myself.

Now, pretty please…?

Normally, whenever you do this:

var mic:Microphone = Microphone.getMicrophone();

The Flash Player automatically opens this panel to ask the user to allow the microphone to be connected:

Of course this panel is never invoked if the user has the settings set to always allow or always deny, but very few do.

When this sucker never presented itself, I naturally thought that I was doing something wrong. Let’s face it, that’s the most probable cause. But after a while I noticed that the problem was specific to Firefox on the Mac. Knowing that SWFObject has had it’s issues with FIrefox in the past, I tried swapping it out for the jQueryFlash plugin, and voilà! How the JavaScript insertion method of the flash content could possibly cause it is beyond me. Honestly I don’t have the JS knowledge or interest to investigate either, seeing as I had a solution.

With SWFObject 1.5 there was a problem causing the stageWidth and stageHeight to be 0 for a certain time after the movie was loaded. That might be relevant in this case as well, but the microphone dialog was supposed to open long after the movie was fully loaded. That kinda rules it out.

So now you know. Don’t spend an entire night on this, like I did.

Get the Flash plugin for jQuery here:
http://jquery.lukelutman.com/plugins/flash/

Faksimile fra jordbarpikene.no—et nettsted laget i 2009 med flashintro a-la 1998!

Anmeldelser av spisesteder på norsk var aldri med i planene for denne bloggen. Det kommer antakelig ikke flere heller, men noen ganger må man gjøre et unntak. For ordens skyld må jeg påpeke at dette kun gjelder Jordbærpikenes avdeling på Hvaltorvet i Sandefjord.

Jordbærpikene er en kjede med spisesteder som etablerer franciser på kjøpesentra. De kan derfor sammenlignes med Cafe Opus og Le Café, men det kan de vanlige anmelderne får gjøre. Jeg er mer opptatt av å se på hva som er unikt med nettopp konseptet Jordbærpikene. Etter 3 besøk siden åpningen av nye Hvaltorvet i Sandefjord sommeren 2010, slår det meg at å vurdere dette spisestedet etter vanlige parametre ikke ville være rettferdig. Baserer man seg på opplevd innsats, kundepleie og kunnskap om næringsmiddeldrift hos personalet, blir det tydelig at dette er et spisested som ønsker å være i bunnklassen. Det finnes ingen annen logisk slutning, så derfor skal jeg vurdere hvordan det presterer på en omvendt skala. Oppsummert blir det da slik:

Første besøk

Sommeren 2009 åpner nyoppussede og utvidede Hvaltorvet i Sandefjord med ikke mindre fire spisesteder. Min lille familie og jeg stikker innom en lørdag under en handletur. Fruen bestiller hamburger, det gjør også jeg. Til sønnen vår på 2 år blir vi anbefalt en pastavariant med pesto. Vi takker ja og finner oss et bord.

20 minutter passerer og vi begynner virkelig å bli imponerte over både ventetiden og mangelen på tilbakemelding. Men skal det bli toppkarakter må for all del ikke delikatessene ankomme med et beklagende smil helt enda. Skal de klare å stå løpet ut? Ja! Etter en hel halvtime ankommer guttungens pasta i hendene på en servitør som gjør alt for å unngå blikkontakt. Enda ett kvarter senere kommer burgerne, fortsatt uten et forståelsesfullt smil eller noe som helst tilbud om kompensasjon for den lange ventetiden. Dette er rett og slett utklassing! Aldri før har jeg opplevd maken til ignorant kundepleie. Og bedre blir det når det viser seg at pastaen min sønn har fått smaker absolutt ingenting, følgelig spiser han heller mine pommes frites. Den smaker iallefall salt, mens burgeren er helt ålreit.

Derfor: Ingen toppscore på mat i denne omgang. Derimot betaler vi 470 kroner, så det står til en sekser på pris, og på service klarer de målene sine med god margin.

Andre besøk

Imponert over innsatsen sist sommer, bestemmer vi oss i januar i år å se om Jordbærpikene kan fascinere oss med sin håpløshet enda en gang. Vi tar et mer kaféaktig besøk denne gangen; kaffe og kake. Min samboer bestiller gulrotkake og kaffe latte. Svart kaffe og eplekake til meg. Men “Den [Jordbærpikene sin eplekake] serveres med krem” (dette får jeg repetert ordrett flere ganger under den påfølgende samtalen). Jeg har aldri vært spesielt begeistret for krem.

–Jeg skal ha eplekake, men tror du jeg kan få den med is istedet for krem?
–Den serveres med krem.
–Ja, jeg vet det, men jeg spør allikevel om jeg kan få den med iskrem.
–Men vi har ikke iskrem
–Kan du ikke bare bytte ut kremen med en liten porsjon fra soft-is-maskinen bak deg da?
–Ja, men det er ikke inkludert, så da må du betale ekstra for det.

Jeg svarer lett leende, som for å vise resten av køen at jeg synes dette var en litt unødvendig diskusjon, at det er helt i orden. Jeg får min eplekake med soft-is, betaler ekstra og finner bordet hvor min samboer har satt seg ned for lengst. Hvis jeg var Jerry Seinfeld ville straks reist meg igjen, spasert tilbake til disken, satt øynene i damen på baksiden og etterlyst kremen. Jeg har nemlig betalt full pris for eplekake med krem, men jeg har også betalt for soft-is og bare fått en av delene. At jeg ikke vil ha kremen er irrelevant i en prinsippiell diskusjon. Jeg har fortsatt betalt for den og damen insisterte jo på å ta ekstra betalt for is. Men køen er lang og jeg er hverken Jerry Seinfeld eller damen bak disken, så jeg slår meg til ro med at det ser ut som det skal bli en bra score denne gangen også.

Matmessig gikk ikke dette besøket så bra. Gulrotkaken var ganske søt, fet og ufrisk, men eplekaken var ganske god, hvertfall med soft-is. Prismessig går dette helt til topps, og spesielt sett i sammenheng med service. Når køen er lang og en kunde ønsker en helt uproblematsik spesialbestilling, ville det være helt uhørt å late som man er serviceinnstillt. Istedet velger personalet her å ta en diskusjon med kunden sin, i påhør av hele resten av køen. Kunden får på denne måten inntrykk av at dersom man betaler over 200 kroner for to kopper kaffe og to kakestykker, skulle det bare mangle at man tar ekstra betalt for en spiseskje soft-is!

Med andre ord: Full pott på både pris og service. Litt trekk for god eplekake.

Tredje (og garantert siste) besøk (hos Jordbærpikene for resten av mitt liv)

Jeg er den typen som tror på tilfeldigheter. Derfor går det ikke lenge før jeg er tilbake på Jordbærpikene etter dette siste, helt spesielle besøket. Denne gang alene. Jeg er noen ærend på kjøpesenteret og har ikke spist middag. Jeg er litt forkjølet og tenker at det passer å få i seg litt sunn middag i dag. Man må jo tenke på immunforsvaret. Inn på Jordbærpikene nok en gang. Klokken er 19.15 og senteret stenger om 45 minutter, så kjøkkenet er allerede stengt. Men salat? Joda! Kylling- og pastasalat har de stående klart til meg. Jeg slår til og tar med en eplemost, tilsammen 155 kroner.

Prisen er kanskje ikke helt imponerende denne gangen, men jeg skulle nok hatt med kamera. Fatet jeg får dette servert på kan nemlig best sammenlignes med et sausenebb. Men hvilken rolle spiller vel mengden når maten vokser i munnen på denne måten! Det er noe eget ved å spise kylling som har vært romtemperert i over et halvt døgn, på en seng av gress og hvitløksdressing, laget på sæterrømme, med tørr foccacia til som er fuktet med harskt smør.

Dessverre var det ikke mye service å beskrive denne gangen, ettersom min omgang med personalet begrenset seg til bestilling og betaling. Muligens blir det et lite pluss for ikke å ha advart meg mot matens tilstand og alder. For det er maten som står i fokus etter dette besøket, eller snarere konsekvensene av den.

Nøyaktig 12 timer etter at jeg forlot Jordbærpikene denne dagen kom det første av en serie toalettbesøk som i skrivende stund fortsatt ikke er over. De er så hyppige at cisterna knapt rekkers å fylles mellom slaga og de er så mange at dehydrering må kompenseres for med elektrolyttpulver. Mat: terningkast seks.

Konklusjon

For å ta den alvorlige hatten på et øyeblikk: Jeg har selv jobbet i handels- og servicenæringen og håndtert kunder med alle slags ønsker stående i 10 timer i strekk. Det er ikke vanskelig. Tar ting for lang tid, sier man i fra og beklager, og helst også tilbyr man et plaster på såret. Ønsker kunden en endring som er uproblematisk, er det sånn det blir. Må man legge på prisen for noe som åpenbart ikke er inkludert er det underforstått og unødvendig å diskutere i påhør av andre kunder (og må man egentlig plusse på prisen når man erstatter krem med soft-is i en bestilling på over 200 kroner en travel lørdag?). Ingen ønsker å være den som lager kø, og ingen ønsker å oppfattes som vanskelig. Og ikke minst; steng heller butikken enn å gjøre kundene syke. Det resulterer bare i dårlig omtale som dette.

Olog (formerly, AILogger formerly OKtrace, formerly text field on stage..) is a logging utility I have been using since the early days. The previous version, AILogger has been the most feature rich to date. But over the years a need to rewrite the whole thing has been growing more and more urgent. It actually started life as an AS1 text field on stage, and was then made into an AS2 class which was then refactored for AS3. But after a while it became evident that it had been patched up too many times to do new things and was in desperate need of some overhaulin’.

It’s about time it took its name from its father as well, so I’m abandoning the scheme of naming it after my employer. (OKTrace = Okular, AILogger = Allegro Interaktiv). It has always been my pet project, so I’m taking it with me everywhere I go from now on. I also wanted a short name, seeing as I’ll be typing it a lot, so Olog it is (the “O” from Oyvind).

So this time it’ll be different, I promise! Olog 0.9 is actually AILogger 1.2 and then some in terms of features, but the first step in making it was “File > New”. It’s completely rewritten, and no copy-paste this time. It has been tagging along during my latest project and so it has seen plenty of action already. I’ve tested it quite thoroughly, but it’s hard to say what happens when you try to live on your own for the first time. That’s why I have humbly versioned it 0.9b for now.

New features

Here are some new things you might like:

• Full featured window interface. Minimize/maximize/close buttons, double click on title bar to minimize. Moveable and resizable.
• Selective line numbers, time-since-movie start and clock time for each line. These can all be turned of or off during run time.
• Filtering of log levels. Pressing number keys 0-5 filters the log to show only those severity levels (color). Esc to escape.
• Automatic update check. Olog will check for a new version once a week if you let it and notify you if there’s a newer version.
• Save log to text/XML.
• Persistent window state. Position, size, minimized/maximized state is remembered so you don’t have to keep moving it out of the way each time you compile.
• Run time markers. Set a new named point-in-time marker, which you can later complete to display load/execution times.
• Support for AILoggerEvents, but Olog has it’s own OlogEvent as well for loosely coupled logging.
• Stacking of repeated messages.
• Full ASDoc documentation.

The olog page on my blog has all the links you need, direct ZIP download, SVN repo access, asdoc documentation, Google Code homepage and even a simple demo. I’ll love to hear it if you have feedback!

The aXbo sleep phase alarm clock

aXbo is a bio-rhythmic Sleep.Phase.Alarm.Clock promising to revolutionize the way you wake up every morning. Put simple, it works by identifying the different phases of sleep in your sleep cycle based on your amount of body movement. It then wakes you up at a time of light sleep, when you are most likely to feel well and rested. Two months ago I got a new job that requires a two hour commute, which means getting up at 6.30 three days a week. After being a tormented B-person all my life, I decided to buy this device i’d heard about in an attempt to make my mornings easier. I have now used it for a few days, so here’s how it’s working so far.

In practicality

First things first: This is a pricey product, costing just shy of 200 euros for the two-person edition. You buy it from www.axbo.com, an Austrian website which in—typical German tradition—defaults to German. Mine was delivered in two weeks “due to strong demand”. The initial experience was somewhat limp in my case because it wouldn’t charge properly. After some time of emailing with their support people, it seemed that there was a problem with the power adapter/cable. Hence I ripped the front plate off, cut away some purposeless plastic thingies, extracted the three AAA batteries and let them charge in a normal battery charger. That worked while I waited for a new power adapter to arrive in the mail.

Setup is done though the menus on the clock with a couple of buttons and a scroll wheel on the side. Pretty standard stuff. My version is made for two people, and any time you do something relating to only one of them, the corresponding icon is displayed topmost in the LCD (see article image). You get a range of six different wake-up sounds, all surprisingly “alarm-ish” for a device that’s comes across as very gentle in all other aspects. I opted for the chirping birds and went to sleep.

While you sleep—some theory

A wristband is what enables the clock to register body movement. They come in man- and lady-size, one of each in my delivery. Inside it is a removable sensor, and the  Austrians are very specific about wearing it the right way on your left arm.

aXbo wristbands used for recording your movements during sleep

As explained thoroughly and way better on the aXbo’s own website, you move less in deep phases of sleep and more in the light ones. The scientists illustrate sleep cycles with a “hypnogramme”, so I thought I’d give it a shot.

In order to avoid copyright infringement, I drew you the illustration to the right. It’s not accurate in any way, but it gets the job done in explaining that you first enter a long, deep sleep phase, followed by waves of gradually shorter and lighter ones. This typically goes on for a period of 7-9 hours for a normal adult.

Waking up

If you wake up remembering your dreams, you most likely woke up from a REM-stage. This is better than waking up from deep sleep, but still not ideal. What you want is to wake up from the lightest sleep stage possible, shown as peaks in the hypnogramme. The aXbo predicts your next light sleep phase and wakes you as close as possible within a 30 minute window. Should your sleep cycle be out of sync with the alarm time you’ve set, the alarm will go off at that time. The same goes for if you forget to wear the wristband, or if the batteries are too drained to safely spend them on the sensing.

One thing I particularly like about the aXbo is your lack of choice when it comes to it’s core features. The wake-up window is 30 minutes, and that’s that. No configuration for a two hour snooze. And speaking of fans of the snooze button (we know who we are!), you won’t have much luck here, because there isn’t any. But what you do get is a button on the wristband that lets you turn the backlight on during the night to check how long you’ve gone without falling asleep. And more importantly, it is also used for silencing the alarm after it goes off . I usually feel a little woozy just after waking up (who doesn’t), so I like to sit upright in bed for a couple of minutes before putting my feet on the cold floor. This might be disobedient to the recommendation in the manual that says to get up immediately, but it works for me.

The aXbo glows when you push the button on the wristband (firmly)

So how does it feeeel?

I’ll be a little cautious for now since I’ve only used it for a few days. But to me this seems like a step forward. The aXbo has yet to wake me up at the precise time I set it to, which can only mean that it has found a better time for me to get up. And so far I have not felt broken and beaten at that time like I usually do. Some mornings however, I have had the pleasure of experiencing something which is a bit of a rarity for me: The feeling of being ready to get out of bed. I suppose it is a little early to attribute it all to the clock, but I’m definitely thinking that there might be something to this device.

I will try to write some more about my experiences with the aXbo after having used it for a month or two. In the mean time, if you want to read up about sleep cycles, sleep phases and what not you probably know where to look.

PS. There’s also free data collection and analysis software for both PC and Mac available from the aXbo website if you want to get utterly German about your sleep. And also, writing the aXbo name with a lowercase “a” and a capital “X” is really not that cool, but apparently that’s its name.

Ads

I just had to link up these hilarious TV ads for the aXbo. I hope their sleep research is better than their metaphors (and the voice actor’s English):

Today I had the dreaded “1131: Internal build error” in Flash Builder coupled with the “Classes must not be nested error” despite no classes actually being nested. Googling around, I found a few posts that provide some tips towards a solution. The most frequent two of which are empty switch statements and ActionScript lines that are not properly terminated with a semicolon. The project in questing uses over 100 classes, so I decided to create a RegExp for use in “Find In Files” to search for lines that were not properly terminated.

As an extra caveat, many types of lines in programming are not supposed to be terminated, so the RegExp is quite long and I have not been able to test it any more than the said 100-class project I’m working on.

NOTE: This might macth some multiline ASDoc comments, empty lines and method argument lists spanning multiple lines as well.

(?sim)(?<!/\*)^\t*((?!\{|\}|@)(?!function|import|class|embed|SWF|if|else|switch|case|while|for|event|try|catch|finally|package|default|//|/\*|\*/)[^;])+$(?!.*\*/)

Here are the posts I found:

• flex’d: “Internal Build Error” or “Classes Must Not Be Nested” error
• Inside RIA: Fixed: “An internal build error has occurred” with FB3 & Galileo
• Tink: An internal build error has occurred (switch statement)
• Michael Imhoff: Internal Build Error
• judah’s blog: Internal Build Error

EDIT: Added “default” to the RegExp. If anyone has any improvements to this, please let me know. Especially on how to make it not match so many empty lines.

Before reading on, you probably wonder if I’m a fanboy myself. The answer to that is both yes and no. Yes because there’s no denying the abundance of Apple made devices and solutions that enrich my daily life, both professionally and personnally. No because I have no problem recognizing the faults and strangeness to be found in the Apple eco system. But this is not about Apple in general, but the specific case of the path Apple has chosen when it comes to app third party development, approval and distribution.

Alex Payne writes on his blog:

The iPad demonstrates that if Apple is listening to these complaints, they simply don’t care. This is why I say that the iPad is a cynical thing: Apple can’t – or won’t – conceive of a future for personal computing that is both elegant and open, usable and free.

This pisses me off because it lacks perspective. If a company is manufacturing products in low-cost countries, well aware that the cheap production price comes at a high health price for the workers—and lets face it, maybe Apple is— then that’s cynical. But choosing a strategy that locks as much as possible of the inner workings of a commercial device down, simply isn’t. It might be disappointing at worst. Some argue in their own right that it’s unwise. But the bottom line is that it’s the right of any business, just as it’s the consumers right to choose not to spend their money there. The majority of western world economies are based on this general principle, and whether we like it or not, it applies to Apple as well. Complaining about cynicism in this context tells me you haven’t thought this through.

As explained by Steve and his subordinates on numerous occations, Apple believes they need control over as many aspects of their production and delivery chain as possible in order to deliver the best user experience they can. Remember, this is a belief converted to a strategy that Apple applies to the products they make and own. This has enabled them to create breakthrough products that raises the bar for everyone else in the industry and has led to real paradigm shifts in the way we work, play and communicate. HTC, Nokia/Symbian and the rest haven’t even come close in terms of sales and widespread adoption. No matter how hard you try and pick that statement apart and devaluate it, there’s no denying the fact that the sales, adoption rate and most importantly; customer satisfaction tell the same story. Apple puts this down to the very same platform model that’s been getting the worst of the tech press lately. You may argue that an equal success would have been possible if Apple had taken their combined product design, UI design and engineering wizardry and walked the open road, and you may even be proven right one day. But so far that’s been the path of their jealous competitors.

What I explain to many fresh switchers from PC to Mac is that to get the best experience you kind of have to buy into the whole eco system of the Mac. I don’t particularly like to give that advice, but it’s the truth. Apple has a vision. Where that vision deviates from many other’s is in the holistic nature of it; the fact that Apple products are designed to work best with other Apple (approved) products and to make more decisions and assumptions on the user’s behalf. To make all this possible it makes sense to control larger parts of the environment the product lives in.

As a user interface developer, I’m the middle man between the designer and the back end developers, which puts me at the center of UI/business logic debate. From this experience I know how challenging it can be to get a success from the collaboration involving just three creators that might even be used to working with each other. The designer has the vision, I may share it and execute it or break it depending on several factors. The backend guy might do either himself. Expand that example to involving, hardware, firmware, OS, software, peripherals and third party providers, and you can easily see why anyone might choose to keep this all under the same roof, within the same company culture, under the same visionary leader. You can easily say it’s hard enough as it is without providing the means for others to mess with it all they want.

I suspect that inside most of us, we like the idea of openness an sharing. I’m no different and as a Flash Developer I try to make my own contribution whenever I can. If Apple were to go 180 in the question of an open platform, I would certainly applaud them for it. Until then I’m a generally happy, relatively IT problem-free participant in the Apple eco system.

…and I’m not getting an iSlate iTablet iTampon iPad because I also think it’s an oversized iPod Touch and I don’t have a need for it. Loving my iPhone though!

EDIT: A few links to great posts on the subject:

• I Love Walled Gardens, by Rory Marinich
• jaggeree /Blog : : Why the iPad may be just what we need for Digital Inclusion
• Stephen Fry: why the Apple iPad is here to stay | The Guardian

Download SlowLoader.as

It works very much the same way as the Loader class with the only difference being that you add your event listeners directly to the SlowLoader instance instead of the contentLoaderInfo instance of the Loader instance. Other than that it dispatches the same events as the Loader class does so it should be fairly simple to swap it for a regular Loader when you’re done. I’ve also included and example class. Here’s an excerpt of it:

1
2
3
4

var l:SlowLoader = new SlowLoader();
l.addEventListener(ProgressEvent.PROGRESS, _updateProgress);
l.addEventListener(Event.INIT, _showImage);
l.load(new URLRequest("file.jpg"), 512, 0.9);

NOTE: SlowLoader was developed for my own use, which means that it dispatches AILoggerEvents for printing log messages from it. AILogger is also included in the ZIP file and you can read more about it here. If you do not wish to use it, feel free to strip these lines out of the class.