Idle Time

Why you should almost always write a test app for your Radar bug reports

2011-11-09T19:23:59Z

You’ll understand the bug better. This means you can write a better bug report, which will help Apple fix it more quickly (meaning you may get the fix more quickly).
They’ll understand the bug better. This, too, helps Apple fix it more quickly.
You may find that it is not a bug in the API at all, but that you were misusing it. Perhaps you were using something on a thread that you shouldn’t have been, or expecting some argument to be used a certain way when it’s actually used differently.

In this case, you may be able to use the API after all, saving you the time you would have spent hacking around a non-bug. This also saves them the time they would have spent triaging and eventually responding to a non-bug.

If your misunderstanding was borne out of poor documentation (misleading, inaccurate, vague, incomplete), you can file a bug report about that instead. Then the documentation gets better and future users of the same API avoid making the same error you did.

A test app isn’t appropriate for every kind of Radar, but when it is, including it helps everyone.

iOS device user guides on the iBookstore

2011-10-16T22:00:56Z

Apple has user guides for their three iOS devices (not counting the TV, in which iOS is an implementation detail), for both iOS 4.3 and 5, free on the iBookstore:

iOS 4.3

iOS 5

Much faster

2011-10-15T23:35:52Z

I’ve just pushed a couple of improvements to my ISO 8601 date formatter. Previously, it was pathetically slow compared to C standard library parsing and unparsing; now, it is faster.

Timing ISO8601DateFormatter
Time taken: 0.130194 seconds
Number of dates and strings computed: 10000 each
Time taken per date: 0.000013 seconds
Timing C standard library parsing and unparsing
Time taken: 0.192645 seconds
Number of dates and strings computed: 10000 each
Time taken per date: 0.000019 seconds

You’ll want at least revision [61d2959c6921] or later.

My thanks to Sam Soffes and Rudy Richter for alerting me to the speed problem.

Edited at 16:35. Previously, it was almost as fast as C stdlib. Now it is faster.

Desktop picture: Yawning Void

2011-09-16T05:10:06Z

This is a desktop picture for Macs running at 1366 by 768, such as the 11-inch MacBook Air:

No, it’s not pure black. Yes, that bar at the top is part of it.

It’s meant to be used at that resolution and no other, with menu-bar translucency turned on. Scaling it, especially vertically, will make it look wrong.

If you want to adapt it to a different size, here’s the original document, editable in Lineform. You should scale the document and the background to the desired screen size, and the menu-bar background to the desired width.

Conferences 2011

2011-09-14T22:31:29Z

It’s that time again! Just like last year, there are a bunch of different conferences going on; unlike last year, I’m not going to even attempt to list all of them.

The two that I have a reason to mention are:

Voices That Matter. This time it’s in Boston, November 12 and 13. Their early bird pricing is still on through September; I’ll let their site tell you more. As I do whenever I mention it here, I have a coupon code for it, which is BSTBLOG. As usual, due to time and expense constraints, I won’t be attending this one.
MacTech Conference. I’m presenting again—same topic as last year, how to recognize, find, and fix bugs in Cocoa applications, but this time it’s the Xcode 4 edition. The early bird period has ended, but you can get the same $500 off by signing up through this referral link. The time and place is November 2, 3, and 4 in Universal City, California.

Last year at the MacTech Conference, I brought with me some of my useful Cocoa links business card. I’ll be doing that again this year, so if you attend the MacTech Conference, feel free to ask me for one.

I hope to see you at the MacTech Conference!

SD card sleeve

2011-07-10T09:44:51Z

If you have an SD card without a case, you may find this handy.

A PDF file from which you can print out nine sleeves per US Letter sheet. Make sure you print at 100% scale.

Assembly instructions

Cut out a sleeve along the thick lines.
Place the card in the center of the sleeve so that it is outlined by the thin lines.
Fold the bottom (rectangular flap) over first.
Fold the side flaps over.
Secure the bottom and side flaps with one square piece of three-quarter-inch Scotch tape.
Fold the top flap over and inside.
Flip the sleeve over and label it on the seamless side.

How to make the Help key do something useful

2011-06-14T09:52:11Z

If you want to see the techniques explored in this blog post in a working application, download ContextHelpTest and/or its source code.

If you’ve used Mac OS X with an Apple extended keyboard of some sort, chances are you’ve seen this:

That’s the cursor that comes up when you press the Help key. And every time, if you click while that cursor is up, you get a beep and the cursor changes back. (If you press a key instead, the cursor changes back and the keystroke goes through, which often will still get you a beep.)

So most of us probably forget the Help key exists, and curse it when we are reminded of it by pressing it by accident.

But what does it do, really? What is it meant to do?

Every responder can respond to a message called helpRequested:. The default implementation is to ask the help manager for the attributed string set as help for itself. If you’ve never set any help for it, then the help manager will return nil, and the default helpRequested: implementation will pass the message on to the next responder. If you have set help for the responder, then it will tell the help manager to show that help.

So here’s what you need to do:

To associate a help text with a view or other object, send the help manager a setContextHelp:forObject: message, passing the help attributed string and the view/other object. When the object is a view, this is all you need to do for Help-clicking on the view to do the right thing.
To programmatically show context help for an object, use showContextHelpForObject:locationHint:. Note that you pass the object to look up, not the help text, here. The location hint is where the user might have Help-clicked to bring up the context help.
To make your custom view able to show context help for things it draws within itself, override helpRequested:, find what the user clicked on, lazily set the context help for the clicked object (if appropriate), and look it up. If the user didn’t click on anything or you don’t have any help worth providing for it, pass the message on to super.
To programmatically enter Help-key mode, send the activateContextHelpMode: action message to the application object. If you want to make a control or menu item in a nib do this, connect it to that action on the First Responder.

Note that the help manager does not retain your definable objects. If an object that has help set for it is deallocated, that will cause a crash later on. Therefore, when setting context help for a view, the view itself should do so within its initWithFrame: (or other designated initializer) and initWithCoder: methods, and remove itself from context help in dealloc. (I don’t know how this goes under GC or ARC.)

You might also have noticed that I’m not simply saying “view” or “responder”. The help manager does not restrict you to setting help for responders or views; any object can have context help set for it. This includes model objects. This is very, very useful for implementing a view that does selective context help on things within it: You set context help for each model object, and the view tells the help manager to show help for the clicked model object.

When setting context help for a non-responder, the controller that owns it should do that, and should remove the object from context help before releasing the ownership.

So, here’s a test app.

Context help works the usual way on the word-count field:

The text view is a subclass of NSTextView that implements helpRequested: by determining what word the user clicked on (by sending itself characterIndexForInsertionAtPoint: and then using a CFStringTokenizer to walk through its words) and then looking that word up in the dictionary.

Naturally, since not everybody has a Help key anymore, I provided an alternative.

I look forward to seeing what uses you come up with in your apps for this.

The Temporal Orphanage

2011-06-01T02:11:10Z

The Temporal Orphanage was a novel solution to the problem of parentless children.

Every child who entered the Orphanage had to sign an agreement stating that they would return in 20 years. As the only licensed user of time-travel technology, the Orphanage used it to send the 20-year-old orphan back in time 20 years to be their own adoptive parent.

Deferments were granted, on a case-by-case basis, to orphans who would eventually marry. The Orphanage preferred the children to be raised by couples, so they granted nearly every request, but undeferred single parents were not uncommon. Every orphan found out within a month of their acceptance whether they would be single or married when they arrived to pick themselves up, and no review was necessary at the time of the deferment application because they already knew whether they would accept it.

A few new laws had to be passed shortly after the Orphanage commenced operations. Some were amendments or repeals to legislation that had assumed time travel did not exist or was completely banned, but one new law that could be tied directly to the Orphanage required life insurance companies to consider the number of years that each insured person lived, not merely the subtraction between their dates of birth and death.

The Orphanage was financed in two parts. The first, and minor, part was by a toy store occupying the other half of the building. Some orphans simply kept all of their toys as they grew up to bring back with them all at once, but this was disfavored by the Orphanage, both because it did not bring in income and because the greater mass made the travel more expensive.

The other part was an apartment complex. Grown-up orphans would begin renting or buy their own residence in their late teens, but then have to go back 20-plus years to a time when they had no home besides the orphanage. Each parent who arrived rented an apartment within the Orphanage’s own apartment building—guaranteed to have an opening—until they could find another, cheaper temporary apartment elsewhere. The trickiest part was remembering to pay the rent upon returning to the apartment they’d left a calendar month/20 biological years ago.

The Orphanage was almost closed down by OSHA, but managed to remain open with the promise of no further hiring, after a power surge uncaused the deaths of all of the staff.

How to make me lose all interest in your app and not even want to try it much less buy it

2011-04-26T22:29:45Z

Choose any—or, preferably, none:

Make custom buttons, but don’t hire a professional designer to design them. Draw your UI in your pirated copy of Photoshop and make the best buttons you, fellow non-graphically-superpowered programmer, can manage, which look like you downloaded them from GeoCities in 1995 or got them out of a “1001 Buttons!” book from the same year.
Make custom UI controls (especially buttons) simply because you can.
Fill your App Store page’s “screenshots” section with images that are not purely screenshots. Showing an iPhone 4 with your app on it is a minus. Showing an older iPhone is another minus. Putting in your own ~~inane blather~~ marketing copy with your paint program’s text tool is a minus. Putting the iPhone and/or text on any kind of background is a minus. Any image that does not show the app at all is 500 minuses.
Show screenshots, but only of some of the app. Leave me wondering whether your app has the feature or UI pattern I’m looking for. (If your app is free, I’ll try it and find out. If it’s not, I won’t.)
Custom backgrounds without (good) custom UI. Extra debit if your background is plain white.
Abbr btn nms.

How to keep me actually interested and maybe even get me to buy your app:

If you make custom UI, make it awesome. Make a truly original UI that would belong on the cover of Macworld. Make it a custom UI with a purpose that guides and justifies the customizations. (Beware the difference between “purpose” and “theme”.) Otherwise, stick to plain Cocoa Touch controls wherever possible. Functional beats ugly.
If you go functional, follow the HIG. Either way, keep things clean and well-organized. Don’t force too much into a single screen. If you “have to” pack multiple things on a line, that’s too much. If you “have to” abbreviate words, that’s too much. Consider cutting features; simplicity is a virtue. If you need to break things out into other views, do it.
The screenshots section is for screenshots only. If you need to indicate a gesture, composite in a finger and an arrow, and don’t do that in more than one screenshot. No added text. Ever.

Don’t miss the comments. I’m sure some of you have some other don’ts to suggest that I forgot.

Portal 2

2011-06-12T22:44:37Z

The best works of fiction all have in common a certain feeling.

It comes at the end. You’ve finished it. There is no more; you know this, and it hurts you, because you want more, you want the enjoyment you’ve just had to continue forever, and yet you know that if there were always more, if it ran forever, eventually it would get boring, so it is good that is over, and yet it hurts.

Portal 2—which is great, all the way through—leaves you with that feeling. The ending is great, the best ending I’ve ever seen in a video game, and it hurts.

You should play it.

Play the first one first, and then play the second. And then you should probably play them both again—I know there’s some stuff I’ll view differently when I play Portal 2 the second time.

The only thing it left me wanting was a soundtrack album. I only bought the one song (you know the one) from the Orange Box soundtrack, but I would happily buy the whole soundtrack to this game. The music is as wonderful as the game it accompanies. I hope, someday, preferably someday soon, I can go to the iTunes Store or Amazon MP3 and buy it.

Valve and everybody else involved in making this game (and the original): You rock.

EDIT 2011-06-12: Just found this phenomenon on TVTropes. (To be clear, they had it first.)

Writing, n.

2011-03-24T23:01:58Z

Over on Tumblr (where I have also started writing), Andy Matuschak and Christopher Bowns have challenged each other:

Long story short: Andy and I threw down our respective gloves after throwing back the third glass of whiskey, and came up with this: every Tuesday, we’ll spend 20 minutes of our respective shuttle rides to work writing something. It doesn’t matter what, but when those 20 minutes are up, you publish it.

After Christopher published that, Colin Barrett entered with this piece. Discussion ensued on Twitter, as it so often does, and it included this tweet from Christopher:

@cbarrett Perfect. I think “overthinking it” can cripple your writing, but it’s hard to let go of, because it’s so useful in engineering.

I responded there, but I’d now like to expand in a somewhat different direction here.

Writing programs is writing.

Consider this: If you write a program that no human can read, you have written it badly, and may have even written an outright bad program. Switch out “program” for “manuscript” and I hope you see my point.

Don’t confuse this with literate programming. That has you write a more-or-less human-only text, and then run a program such as WEB or CWEB to translate it to source code.

The problem with literate programming is the problem with all translation from one language to another, especially automatic translation: Error.

Just as translating a human-only text from one human language to another human language can produce a garbled mash, so can translating a program from one language to another produce a nonsense, or at least broken, program.

Hence the justified suspicion of programs that “upgrade” a program even just from one version of the same language to another: It isn’t the same language; not really. Similar, but not the same. Going from Python 2 to Python 3, for example, is not much different from going from 18th-century English to 21st-century English. Do these words mean the same thing? Maybe not. This is why such translators invariably come with warnings to check the hell out of the result.

No, I’m not talking about literate programming. I’m talking about regular programming, where you write the true text of the program, the text that the interpreter interprets or the compiler converts into machine code.*

Programming is a fusion of a couple of skills. It’s often called “software engineering”, but that’s only half of it. Writing is the other half. I define “writing” here as writing text into an editor, whatever the language, and “engineering” as designing a thing to be built. Things like OOP, unit testing, and design patterns are aspects of software engineering. Things like DRY, commenting practices, naming practices, and style rules are aspects of writing.

If you write a program well, you write it not only for the interpreter or compiler, but for any humans who will read the program after you, including yourself. It is a text like any other.

Writing a program is writing. Every rule, observation, and prescription you apply to writing for humans only, apply also to programming, and vice versa. If the rule does not work, chances are it was not a good rule to begin with.

The application delegate and the new singletons

2011-03-19T00:26:59Z

Here is a global variable:

Wizard *gWizard;

I’ll call this a zeroth-order global, on the premise that I need to talk to exactly zero objects (including classes) to gain access to this object.

Next, let’s look at a singleton:

[Wizard sharedWizard]; //hope he's not busy

I’ll call this a first-order global, as we need to ask the class for it (1 step) to gain access to it.

Now, here’s a second-order global:

MyAppDelegate *appDelegate = [[UIApplication sharedApplication] delegate];

(I use UIApplication here because I see this most frequently in Cocoa Touch code, but the pattern applies equally to Cocoa.)

And here’s a third-order global:

Wizard *wizard = [appDelegate wizard];

I need to (1) ask the UIApplication class for the application object, (2) ask that for its delegate, and (3) ask that for the wizard. (Assume here that wizard is a property, not a factory method that creates Wizards on the fly.)

None of these is any less global. If I can get to it from anywhere in the program without knowing about it directly, it is global.

Therefore, all the problems of globals apply:

What if two threads want to use the same Wizard?
What if the Wizard has a delegate of its own, and I have two objects that want to be its delegate?
What if the Wizard keeps internal state that may be corrupted by multiple objects trying to use it? (Nothing should have to worry about this outside of the Wizard itself.)

Your application’s objects form a graph. It should not be a complex one like this:

Whenever you have paths bouncing around off of other objects like that, that’s a problem. The red arrows in the problem graph show where you violate the Law of Demeter.

Your object graph should, instead, be straightforward:

Note that each of your controllers should own—or, if you prefer, hire—a Wizard all to itself. This eliminates contention between objects and reduces the likelihood of contention between threads (assuming each of the owning objects is supposed to only work on a single thread and not juggle multiple threads).

If contention is not a problem and you have a good reason why there should be only one Wizard, such as memory pressure or union regulations, then use a singleton. But use a real singleton, and only when necessary, and beware of singletons in disguise.

The new and improved Cocoa links card

2011-03-15T15:16:16Z

I’ve previously mentioned that I made a business card full of useful Cocoa and Cocoa Touch links to give to new Cocoa and Cocoa Touch programmers at events such as CocoaHeads.

Today, I have updated it and given it a web page. 1-up and 10-up (US Letter) PDFs are available there, as well as the full list of unshortened links.

I encourage you to print out the 10-up onto perforated business card paper, or have it professionally printed (keeping in mind that you probably won’t need 1000 of them), and make the cards available to novice Cocoa and Cocoa Touch programmers at the CocoaHeads or NSCoderNight events you attend. Just please be sure to print both sides, since my credit link is on the back.

Mentoring

2011-03-09T04:08:16Z

I originally wrote this for the Adium development list, in a discussion of the upcoming Google Summer of Code, for the benefit of those of our developers who have never mentored students in GSoC before and may be considering doing so. Read this in that context; for example, “our” means “the Adium project’s”.

Work with students from the very beginning on the quality of their [application] submissions. 90% of the submissions will be crap. Look past this. See what lies within. If it can be improved, try to get them to improve it. Those who do will be good students.
Spur your student to work on code. Make sure they’re committing at a regular and satisfactory rate.
Ensure your student actually writes code and doesn’t just crib together tutorials and/or Stack Overflow answers and/or ask you to provide code* for various tasks they need to accomplish. Wildly varying coding styles, inconsistent variable and method naming, and poor indentation are warning signs.
Communicate constantly. This includes the aforementioned spurring your student to work as well as being available to answer any questions they have about where things are in our code base, what they need to do to achieve certain goals or specific sub-tasks, etc. These questions are virtuous; you should encourage them, just short of demanding them. The student is not that only in name; they are here both to write code and to learn.
Find a medium that works for both of you. For me, email (or Twitter, nowadays) would be best. Maybe you prefer IM, or even voice chat/phone (if it isn’t too expensive). Don’t try to force your habits on the student; if you love the phone but they hate it (or vice versa), a happy medium will work better.
Be sure they understand and use Mercurial and good VCS practices generally. Frequent, discrete commits; neither waiting “until it’s done” to commit (it should compile) nor committing half-done work periodically (e.g., daily) nor committing amalgams of unrelated work (they should commit specific sections that comprise a single change).
Nowadays, I recommend that you have them fork our Bitbucket repo and push to their fork.
Review their code constantly. Subscribe to the commits list (or their fork’s commits feed) and review everything they write.
Read their commit messages, not just their code. Lists are a warning sign (unrelated changes lumped together). Inadequately describing the change is also a problem. Work the student out of these habits as soon as possible.
Don’t wait until mid-term exams to sit your student down for a serious talk about their work or lack thereof. If they’re committing garbage, set them straight as soon as possible—do not wait. If they don’t commit, get them writing and committing as soon as possible.
Always be ready to fail your student. Be compassionate, understanding of life’s realities; they’re not a slave. But they are here to work, and if they don’t do the job or if they do a bad job, be ready to fail them.
Make sure they know where they stand. If there’s 1–2 weeks before exams and they’re still in danger of failing, make sure they know what’ll happen if they don’t shape up.

I can’t claim to have been perfect in all of these points in my own mentoring (many of these I learned by not doing them), but it’s what I’ve found works.

There might also be something on the GSoC sites about this. Some viewpoints vary, particularly along the leniency-to-hardassness spectrum.

If you are not willing to do all of this, or don’t think you’ll have the time, you should not mentor a student.

* Six words that should worry every mentor or other help-offerer: “Can you show me a sample?” ↶

Apple documentation search that works

2011-03-07T09:36:24Z

You’ve probably tried searching Apple’s developer documentation like this:

Edit: That’s the filter field, which is not what this post is about. The filter sucks. This isn’t just an easy way to use the filter field; it’s an entirely different solution. Read on.

You’ve probably been searching it like this:

(And yes, I know about site:developer.apple.com. That often isn’t much better than without it. Again, read on.)

There is a better way.

Better than that: A best way.

Setup

First, you must use Google Chrome or OmniWeb.

Go to your list of custom searches. In Chrome, open the Preferences and click on Manage:

In OmniWeb, open the Preferences and click on Shortcuts:

Then add one or both of these searches:

For the Mac

	Chrome	OmniWeb
Name	ADC Mac OS X Library
Keyword	adcmac	adcmac@
URL	http://developer.apple.com/library/mac/search/?q=%s	http://developer.apple.com/library/mac/search/?q=%@

For iOS

	Chrome	OmniWeb
Name	ADC iOS Library
Keyword	adcios	adcios@
URL	http://developer.apple.com/library/ios/search/?q=%s	http://developer.apple.com/library/ios/search/?q=%@

Result

Notice how the results page gives you both guides and references at once, even giving specific-chapter links when relevant. You even get relevant technotes and Q&As. No wild goose chases, no PDF mines, no third-party old backup copies, no having to scroll past six hits of mailing-list threads and Stack Overflow questions. You get the docs, the right docs, and nothing but the docs.

For this specific purpose, you now have something better than Google.