---
title: "Timezone review comments: is the value an instant or a wall time? | Proofline"
description: "A timezone comment is right when the code treats a wall-clock time as an instant, or an instant as a wall-clock time, where the two differ."
url: https://proofline.sh/learn/ai-review-timezone-comment/
---

[Learning center](/learn/)

# Timezone review comments: is the value an instant or a wall time?

A timezone comment is right when the code treats a wall-clock time as an instant, or an instant as a wall-clock time, where the two differ. Decide which kind each value is meant to be. Change the code where a conversion mixes them, dismiss the comment where a documented convention fixes the zone, and settle the rest with a test run in two zones other than UTC and across a daylight saving change.

Code review The Proofline team November 22, 2026 4 min read

## Name the kind of time first

Most timezone comments argue about two kinds of value:

-   An instant is a point on the timeline, the same everywhere, such as a log timestamp or a token expiry. Python calls a `datetime` with an offset "aware" ([aware and naive objects](https://docs.python.org/3/library/datetime.html#aware-and-naive-objects)), PostgreSQL stores instants in `timestamptz`, and BigQuery in `TIMESTAMP`.
-   A wall-clock time has no zone of its own, such as a store's opening hour or a daily 01:00 backup. It is a naive `datetime`, a PostgreSQL `timestamp` without time zone ([date/time types](https://www.postgresql.org/docs/current/datatype-datetime.html)) or a BigQuery `DATETIME` ([data types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)).

A naive value can also stand for an instant by convention, usually "naive means UTC". That convention is correct as long as every reader and writer follows it, and the bug appears where one of them uses the machine's local zone instead.

So the first question about a comment such as "this datetime is naive" or "this ignores the time zone" is which kind the value is supposed to be. The second is where it crosses into code that assumes the other kind.

## A Calendar argument the driver now ignores

In October 2026, a pull request to Google's BigQuery JDBC driver changed the `Calendar` overloads of `setTimestamp` and `getTimestamp`. The author explained the bug: the old code "extracted the JVM-local wall-clock fields (`ts.toLocalDateTime()`) and re-anchored them in `cal.getTimeZone()`," "shifting the epoch instant whenever the `Calendar` timezone differed from the JVM default timezone." The fix ignores the `Calendar`, because "A `java.sql.Timestamp` already represents an absolute UTC epoch instant (`milliseconds + nanos`)," "and BigQuery's `TIMESTAMP` type is a timezone-aware absolute instant." ([pull request](https://github.com/googleapis/google-cloud-java/pull/14640))

gemini-code-assist's review summary objected that "ignoring the Calendar parameter entirely may cause issues with timezone-naive DATETIME values, which should be interpreted using the provided Calendar's timezone." ([review](https://github.com/googleapis/google-cloud-java/pull/14640#pullrequestreview-5493727720)) The inline threads are resolved and hidden. The author pushed a commit titled "address pr feedback", and the pull request merged on 13 October 2026 with the `Calendar` still ignored:

```
   public void setTimestamp(int parameterIndex, Timestamp value, Calendar calendar)
       throws SQLException {
     checkClosed();
-    setTimestamp(
-        parameterIndex, BigQueryTemporalUtility.convertTimestampWithCalendar(value, calendar));
+    setTimestamp(parameterIndex, value);
   }
```

[Diff](https://patch-diff.githubusercontent.com/raw/googleapis/google-cloud-java/pull/14640.diff)

Both sides have a point, and the code decides between them. JDBC says a driver "uses the `Calendar` object to construct an SQL `TIMESTAMP` value" ([`PreparedStatement.setTimestamp`](https://docs.oracle.com/en/java/javase/21/docs/api/java.sql/java/sql/PreparedStatement.html#setTimestamp\(int,java.sql.Timestamp,java.util.Calendar\))), which matters for databases that store wall-clock time. For this driver, the question is which BigQuery type a `Timestamp` parameter becomes. In `BigQueryTypeRegistry.java` at the merge commit, both the `TIMESTAMP` and the `DATETIME` descriptors accept `java.sql.Timestamp`, but registration uses `putIfAbsent` and the `TIMESTAMP` descriptor registers first. A bound `Timestamp` is therefore sent as `TIMESTAMP`, an instant, and the author's reasoning holds for the setters.

The tests back that up. The changed tests run the `Calendar` overloads with `America/New_York` and `Asia/Tokyo`, with a fixed instant, `new Timestamp(1700000000000L)`, and assert that the same instant comes back. What we did not check is the read path: whether `getTimestamp` with a `Calendar` can return a `DATETIME` value, which is the case the bot named. That needs its own test with a `DATETIME` column.

## A naive datetime that is the convention

The opposite comment, "replace this naive datetime with an aware one", can be wrong for the same reason. A `google-cloud-python` pull request merged on 13 November 2026 replaced the deprecated `datetime.utcnow()` in the ndb library. Its description warns that `DateTimeProperty._validate()` "rejects offset-aware values unless the property is configured with `tzinfo`", so "A plain substitution would therefore make `auto_now` raise `BadValueError` for every property without `tzinfo`." The helper it added strips the offset "to keep returning the naive-UTC value `ndb` has always stored and compared." ([pull request](https://github.com/googleapis/google-cloud-python/pull/18186)) Here naive means UTC by contract, and an aware value is the bug.

## Test in zones that are not UTC

CI usually runs in UTC, where a naive local time and a naive UTC time are the same value. A test of the overdue-job check in `vllm-project/aibrix` passed in CI and failed on a developer machine in `Asia/Kolkata`, because it built a naive local time that the code read as UTC ([pull request](https://github.com/vllm-project/aibrix/pull/3000)). Run timezone tests with at least two non-UTC zones on opposite sides of UTC, as the JDBC tests do, and include a daylight saving change. In Python with `zoneinfo`:

```
ny = ZoneInfo("America/New_York")
datetime(2026, 11, 1, 1, 30, tzinfo=ny).utcoffset()          # -4 hours
datetime(2026, 11, 1, 1, 30, fold=1, tzinfo=ny).utcoffset()  # -5 hours
```

The same wall time occurs twice on that date. Adding `timedelta(days=1)` to midnight on 1 November gives midnight on 2 November, 25 hours later. Comparing a naive and an aware `datetime` raises `TypeError: can't compare offset-naive and offset-aware datetimes`.

## Decide from the kind of value

| What you find | Answer |
| --- | --- |
| A conversion reads wall-clock fields from an instant, or the reverse | Change the code, and test with two non-UTC zones |
| The value is naive, and the code documents and enforces "naive means UTC" | Dismiss, citing the convention, as ndb's validation does |
| The value is naive, and some reader or writer uses local time | Change it to an aware value or a fixed convention at that boundary |
| The value is a wall-clock time, such as a schedule, and the comment asks to store UTC | Dismiss, and keep the zone name beside the value |
| The code adds days or hours across a daylight saving change | Test the change date explicitly |

If a date already shows one day off in the browser, the guide to [finding where the date shifted](/learn/date-off-by-one-timezone/) traces the conversion from the API response to the screen.

## One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. [Eligibility and fair-use terms](/free-code-review/).

[Start free with GitHub](https://proofline.sh/orgs/plan?offer=free_month)

## Related reading

-   ### [A date shows one day off: find where the value shifted](/learn/date-off-by-one-timezone/)
    
    Schema conflicts The Proofline team November 20, 2026 5 min read
    
-   ### [Settle an off-by-one review comment with a boundary test](/learn/ai-review-off-by-one-comment/)
    
    Code review The Proofline team November 22, 2026 5 min read
