In the world of computing, there is a four-letter acronym that gets bandied about whenever someone asks a question that could have been resolved by consulting documentation -- RTFM. It stands for "Read the Fine Manual"... although in more inflammatory circumstances, one might use a more offensive phrasing, but this is a safe-for-work blog, so we're not going there. :-)
Today I was reminded that there are times where even the manual might be worthy of a second opinion. We were focused on some new code that involved time zones. The language for the development, PHP 5, has some facilities for dealing with the pitfalls that come come with handling time caculations around the globe. This functionality is neatly packaged in the
Under the hood, PHP leverages the well-established zoneinfo database for figuring out the difference between the time at a given location and Universal Coordinated Time (UTC), so references to time zones are expressed using the region codes provided by the database. For the most part, these codes look like
The
As the code was being written to make use of this feature, I noticed that an older version of the documentation did not show support for the additional arguments. Moreover, the older version said it was true for PHP versions 5.1.0 and later, while the newer version said that there was no version information available.
We then ran some test snippets and verified that it wasn't supported in our version of PHP. It's not like we're running an old version of PHP either. It was released in the spring of last year. It turns out that the missing feature was introduced with a commit made back in July of last year and is present in the 5.3 and HEAD branch development, but not in the 5.2 branch.
The moral of the story: When it comes to relying on documentation for an actively evolving open source project, trust, but verify.
Today I was reminded that there are times where even the manual might be worthy of a second opinion. We were focused on some new code that involved time zones. The language for the development, PHP 5, has some facilities for dealing with the pitfalls that come come with handling time caculations around the globe. This functionality is neatly packaged in the
DateTimeZone class.Under the hood, PHP leverages the well-established zoneinfo database for figuring out the difference between the time at a given location and Universal Coordinated Time (UTC), so references to time zones are expressed using the region codes provided by the database. For the most part, these codes look like
<continent or ocean>/<location>, so you have values like "America/New_York" or "Atlantic/Reykjavik".The
DateTimeZone class has a static method for getting a list of recognized values -- DateTimeZone::listIdentifiers(). The current documentation says that the method accepts two optional arguments. The first is a class constant that corresponds to the "continent or ocean" value. The second is an ISO 3166-1 country code. These extra arguments were nice because they would allow us to filter out the results, restricting them to certain regions.As the code was being written to make use of this feature, I noticed that an older version of the documentation did not show support for the additional arguments. Moreover, the older version said it was true for PHP versions 5.1.0 and later, while the newer version said that there was no version information available.
We then ran some test snippets and verified that it wasn't supported in our version of PHP. It's not like we're running an old version of PHP either. It was released in the spring of last year. It turns out that the missing feature was introduced with a commit made back in July of last year and is present in the 5.3 and HEAD branch development, but not in the 5.2 branch.
The moral of the story: When it comes to relying on documentation for an actively evolving open source project, trust, but verify.
Comments for Sometimes, RTFM isn't Enough
Leave a comment