Introduction

Dockerfiles do not support block-comment syntax. There is no native multiline comment token similar to what you might use in C, Java, or JavaScript. If you want a multiline explanation, you write several consecutive line comments that each begin with #. The real challenge is not how to make a long comment. It is how to document build intent without turning the Dockerfile into stale prose.

Dockerfile Comments Are Line-Based Only

The parser recognizes comment lines that begin with #. That is the supported comment mechanism.

1# valid Dockerfile comment
2FROM alpine:3.20
3
4# install curl for health checks
5RUN apk add --no-cache curl

What Dockerfiles do not support is block-comment syntax.

/* not a valid Dockerfile comment */
FROM alpine

So a “multiline comment” is simply a group of adjacent single-line comments.

Use Grouped Comments Before Logical Build Steps

The best pattern is usually to place a short comment group before a related build section.

# Install TLS certificates and curl for diagnostics.
# Keep package surface small to reduce image size and vulnerabilities.
RUN apk add --no-cache ca-certificates curl

This works well because it explains intent and constraints, not only the literal command text. If the command changes later, the comment is still likely to remain useful.

Comment Why, Not What

A weak Dockerfile comment often just repeats the instruction.

# copy app files
COPY . .

That usually adds no value. A better comment explains why the instruction is placed where it is or what build concern it is addressing.

# Copy lockfiles first so dependency installation can be cached independently.
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

That comment explains a build-optimization decision. This kind of explanation is worth keeping in the Dockerfile because it helps future editors avoid accidentally breaking layer caching.

Put Complex Logic in Scripts, Not Huge Comments

If a startup or build sequence is complicated, the Dockerfile should usually stay concise and point to a script rather than contain long explanatory paragraphs.

1# Entrypoint performs dependency checks and then starts the main process.
2COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
3RUN chmod +x /usr/local/bin/entrypoint.sh
4ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

Then the detailed logic can live in the script itself.

1#!/bin/sh
2set -eu
3
4# Wait for the database before starting the application.
5until nc -z "$DB_HOST" "$DB_PORT"; do
6  sleep 1
7done
8
9exec "$@"

This keeps the Dockerfile readable while still preserving useful detail where the complexity actually lives.

Multi-Stage Builds Benefit from Stage-Level Comments

Comments are especially helpful in multi-stage builds, where the purpose of each stage may not be obvious to the next maintainer.

1# Build stage compiles the binary.
2FROM golang:1.23 AS build
3WORKDIR /src
4COPY . .
5RUN go build -o app ./cmd/server
6
7# Runtime stage keeps the final image minimal.
8FROM gcr.io/distroless/base-debian12
9COPY --from=build /src/app /app
10ENTRYPOINT ["/app"]

Stage-level comments are often more valuable than instruction-by-instruction commentary because they describe the overall artifact flow.

Labels Are Metadata, Not a Replacement for Comments

You can store some machine-readable context in image labels.

LABEL org.opencontainers.image.source="https://example.com/repo"
LABEL org.opencontainers.image.description="API service image"

That is useful for tooling and inspection, but it does not replace comments that explain build reasoning. Labels describe the artifact. Comments explain the human intent behind the build steps.

Comment Discipline Matters More Than Comment Length

Most Dockerfile readability problems come from bad comments, not short ones. Stale comments are worse than missing comments because they mislead readers. So a practical rule is:

• comment only where intent or constraints are not obvious,
• update or delete comments when build logic changes,
• and keep detailed operational narratives in scripts or Markdown docs.

That is how you keep comments trustworthy.

Common Pitfalls

• Trying to use block-comment syntax even though Dockerfiles only support line comments.
• Writing long comment blocks that drift out of sync with the actual build logic.
• Repeating obvious commands instead of documenting the reason behind them.
• Duplicating the same explanation across Dockerfile, entrypoint script, and README until the versions drift apart.
• Using comments to hide complexity that should really be moved into a script.

Summary

• Dockerfiles support line comments only, not block comments.
• A multiline Dockerfile comment is just a group of consecutive # lines.
• The most useful comments explain intent, constraints, or caching decisions.
• Put complicated logic in scripts and keep Dockerfile comments concise.
• Accurate, high-signal comments are more valuable than long comment blocks.