How Should a Countdown Handle a Clock Change?
From the earlier reference collection. Read the current software blog.
Calculate time remaining between instants, not by subtracting local clock labels that may jump or repeat.
Clock labels are not elapsed time
A countdown asks how much real time remains before an event. Subtracting displayed local clock values can fail when the local clock jumps forward or repeats an hour. The labels describe a civil-time display; they are not a reliable measure of duration across a clock transition.
For example, during a spring change, a clock may go from 1:59 to 3:00. An event displayed at 3:10 is not necessarily 70 minutes away from a displayed 2:00; that local time may never occur on that date.
Compare timestamps
Represent the current moment and the event as unambiguous instants, then subtract them to get the remaining duration. If the current instant is 06:50 UTC and an event is 07:10 UTC, 20 minutes remain regardless of how either moment appears on a local clock.
For a transit event, first interpret the schedule using the service date and agency time zone. A schedule value such as 25:10 is not automatically an instant; it must be anchored to the applicable service date and converted according to the schedule’s time convention.
Keep the display local and honest
After calculating the duration, show a friendly label such as “20 minutes.” The local arrival time can be shown alongside it, with a date label if the event falls on the following day. Recompute the duration as the current instant advances, but do not derive it by repeatedly subtracting formatted clock strings.
If the source time zone or repeated-hour interpretation is unknown, avoid an exact countdown that implies certainty. Show the supplied schedule information and explain what context is missing.
Test both seasonal boundaries
Test a countdown that spans the spring jump and another that spans the autumn repetition. Confirm that the duration follows elapsed time while the displayed local labels reflect the clock rules. Also test a trip crossing midnight, where the date changes even though no daylight-saving transition occurs.
This approach keeps the countdown meaningful when local clocks behave irregularly. Instants support the arithmetic; local time zones support the human-readable presentation.