Anyone who has ever written software knows how strange some bugs can be. Last week, someone beta-testing my new unified log browser Ulbow reported one of the oddest that I’ve come across. It has lessons for us all.

In my older log browser Consolation, setting times is simple if a tad unfriendly: you just type them in using the standard convention HH:MM:SS, such as 14:36:44, using the 24-hour clock. There’s a minimum of checking, and changing the hour from 14 to 15 requires you to use the keyboard.

 

For Ulbow, I spent a lot of time trying to arrive at the best solution for setting time, and concluded that Apple’s standard DatePicker tool was as close as I could get to perfect. It has lots of flexibility, and can be driven from the keyboard or mouse/trackpad. As it’s part of AppKit, the macOS Cocoa frameworks which are widely used, and is fully supported by Xcode’s graphical Interface Builder, I thought that I couldn’t go wrong.

 

The user sets the time in the DatePicker, and all Ulbow has to do is retrieve the time that they have set there. AppKit handles the control, localisation, validation, and pretty well everything else. I’ve tested Ulbow on both my Macs, doing a wide range of tasks, and it’s now my preferred log browser, so gets an airing pretty well every day, and sometimes intensive use. The DatePicker had worked flawlessly from earliest pre-release builds.

But this user couldn’t enter certain times, before 01:00 and after 13:00, which made it impossible to specify hours such as 00 or 13-23. One clue – which I didn’t spot at first – was his mention of AM and PM.

When I read this, I went off and exercised Ulbow’s DatePicker to exhaustion. I not only couldn’t reproduce his problems, but I couldn’t see how AM or PM came into this: here, DatePicker worked using the 24-hour clock. I’d recently been looking at how to obtain additional calendars, and remembered there’s a control for the expression of time in the General tab of the Language & Region pane. I changed my Time format by unchecking that box, and suddenly realised what had happened: he was working with times using AM/PM, not the 24-hour clock. Why, though, should that alter DatePicker’s behaviour?

I trudged through Apple’s developer documentation on NSDatePicker. There’s no mention of 24-hour versus AM/PM formats, although in the macOS Human Interface Guidelines I saw mention of AM/PM, and a screenshot example. I went back to Ulbow’s source code, and, working with 24-hour time turned off, discovered that the size I had set my DatePicker to was cropping any AM/PM control off. The effects were exactly as the user had explained.

The simple answer then was that anyone trying to use Ulbow’s DatePicker with 24-hour time turned off was only being provided with part of the controls that they needed. I enlarged the space provided to the DatePicker so that any AM/PM setting was in sight and could be changed, and the problem was solved. You could then use Ulbow fully whatever time format was selected.

I’ve since gone back through both the documentation of NSDatePicker and that in the Human Interface Guidelines, and can’t find any warning that DatePicker’s layout, space requirement, and behaviour depend on the setting in the Language & Region pane. There are also two issues arising from this unexpected behaviour. The first is that the size of a DatePicker needs to be different according to that global format setting. With the control long enough to accommodate the AM/PM section, there’s blank space within it if you’ve got 24-hour time enabled.

There’s also an overriding problem with using AM/PM in an app like Ulbow, in which every log entry has a datestamp which is immutably given in 24-hour format. It would be more consistent for the Ulbow user to work throughout using the 24-hour clock, regardless of their preference in the Language & Region pane. But there’s no option in NSDatePicker to override the system-wide setting, so the user is left to convert between 12- and 24-hour time formats in order to work with log extracts.

You can of course change the locale of the DatePicker, which led me off down another rabbithole looking at how that might let me fix my DatePicker’s format using the 24-hour clock, irrespective of the option set in the Language & Region pane. There’s doubtless an answer there, but I currently can’t see the 24-hour setting exposed in the interface to Locale.

Related problems appear to have been common, particularly in iOS, where DatePicker’s human interface is quite different, of course. Among the many ‘solutions’ that have been proposed there is to switch locale for the DatePicker from standard US to GB, which of course wouldn’t work for anyone else who has opted not to use the 24-hour clock.

To put all this into perspective, one of the older references that I turn to frequently for information about AppKit and Cocoa is slightly less than a thousand pages long, but only mentions NSDatePicker in a short paragraph, in passing.

It’s facile to blame Apple for lack of documentation, but in this case, Apple’s documentation is extensive and detailed. There’s a whole book devoted to internationalisation and localisation, but for the life of me I can’t find this issue discussed there. This demonstrates how vast and complex AppKit and macOS more generally have become, how important beta-testing is, and the role of testers. If you discover something that doesn’t work, or doesn’t make sense, please report it to the developer: it may turn out to be something similarly arcane, for which there is a simple fix.

Above all, this shows how software development is a journey for both developer and user, with unexpected twists and turns. It’s really satisfying to resolve such issues, so please help developers to do so.

I’m very grateful to bmike and everyone else who has been testing and commenting on Ulbow, so helping me remove such bugs.