Dependency Step Docs

Dependency step docs are the comments and structure around a Dockerfile's dependency installation instructions that clarify why specific packages are needed, why instructions are ordered a particular way, or why a particular version is pinned — context that is not otherwise self-evident from the instructions alone.

Why Dependency Steps Benefit From Explanation

A RUN instruction installing a package reveals what is being installed, but not necessarily why — documenting the reason, especially for non-obvious dependencies, helps future maintainers understand whether a dependency is still needed when the application later changes.

# libpq5 is required by psycopg2 for PostgreSQL connectivity
RUN apt-get update && apt-get install -y libpq5 && rm -rf /var/lib/apt/lists/*

Without this comment, a future maintainer might not realize this system package exists specifically to support a particular Python dependency, and could remove it without understanding the consequence.

Explaining Non-Obvious Version Pins

When a dependency is pinned to a specific version for a reason that is not self-evident — working around a known bug, avoiding a breaking change in a newer release — documenting that reason prevents someone from "helpfully" upgrading it later and reintroducing the original problem.

# Pinned below 2.0 due to a breaking API change affecting our auth module
RUN pip install "somepackage<2.0"

Explaining Ordering Decisions

When dependency installation is deliberately ordered for caching reasons, a brief comment can make that intent explicit, rather than leaving a future maintainer to potentially reorder instructions in a way that inadvertently breaks the caching benefit.

# Copy only the manifest first so dependency installation is cached
# independently of changes to application source.
COPY package*.json ./
RUN npm install
COPY . .

Why Documenting Dependency Steps Matters

A Dockerfile's instructions alone communicate what happens, but rarely why — a small amount of targeted commentary around non-obvious dependency decisions meaningfully reduces the chance that a future change unintentionally reverts an earlier, deliberate fix or optimization.