4.3.3.5 Non Obvious Comments
A focused guide to Non Obvious Comments, connecting core concepts with practical Docker and container operations.
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.