Non Obvious Comments

Non-obvious comments are comments placed in a Dockerfile specifically to explain something a reader could not easily infer just from reading the instruction itself — a reason for an unusual choice, a workaround for a specific known issue, a constraint that shaped a particular decision.

What Makes a Comment Worth Writing

A comment earns its place by conveying information the code itself cannot — the why behind a decision, rather than a restatement of what the instruction already plainly does.

# Restating what the instruction obviously does already
RUN apt-get update

# Pinned to 3.12 because 3.13 introduces a regression affecting our
# database driver; revisit once upstream issue #4821 is resolved.
FROM python:3.12-slim

The second comment provides context a reader genuinely could not infer from the instruction alone, and that context could matter significantly to someone considering whether to "fix" the apparently outdated version pin.

Documenting Workarounds

A Dockerfile instruction that exists specifically to work around a known issue — rather than reflecting an obviously necessary step — benefits especially from an explanatory comment, since a future reader without that context might otherwise remove it as unnecessary.

# Explicitly setting this env var works around a hang in the base
# image's entrypoint script under certain locales; see issue #112.
ENV LANG=C.UTF-8

Avoiding Comments That Will Rot

A comment referencing a specific, time-bound detail (a current sprint, a temporary ticket) risks becoming misleading once that context is no longer current — comments explaining a durable technical reason age much better than ones tied to transient process details.

# TODO: remove after Q3 migration is done (see JIRA-4521)

This kind of comment requires active maintenance to remain accurate, and easily becomes stale if forgotten.

Why Non-Obvious Comments Matter

A Dockerfile with well-placed comments explaining genuinely non-obvious decisions prevents future maintainers from confusedly "fixing" something that was deliberately set up that way for a reason no longer visible without the comment.