4.3.3.4 Formatting Consistency

Formatting consistency is the practice of applying uniform conventions for capitalization, indentation, line continuation, and instruction spacing throughout a Dockerfile, reducing the cognitive overhead involved in reading and reviewing it.

Consistent Instruction Capitalization

Dockerfile instructions are conventionally written in uppercase, distinguishing them visually from arguments and values; mixing case inconsistently undermines this visual distinction.

from node:20-alpine
WORKDIR /app
run npm install

FROM node:20-alpine
WORKDIR /app
RUN npm install

The consistently uppercase version is immediately recognizable and matches the convention nearly every Dockerfile reader expects.

Consistent Line Continuation Formatting

When a RUN instruction spans multiple lines, formatting the continuation consistently — indentation, where each && line break falls — makes multi-line instructions significantly easier to scan.

RUN apt-get update && apt-get install -y \
      curl \
      wget \
      git \
    && rm -rf /var/lib/apt/lists/*

Applying this same indentation and line-break pattern consistently across every multi-line instruction in the file, rather than varying the style each time, makes the file's structure more predictable to read.

Consistent Spacing Between Sections

Using blank lines consistently to separate logically distinct sections, rather than inconsistently or not at all, helps a reader visually parse the file's structure at a glance.

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

Using a Linter to Enforce Consistency Automatically

Tools exist specifically to check Dockerfiles for formatting and best-practice issues, which can catch inconsistencies automatically rather than relying solely on manual review.

docker run --rm -i hadolint/hadolint < Dockerfile

Why Formatting Consistency Matters

Consistent formatting, even though it has no effect on the resulting image, meaningfully reduces the mental effort required to read and review a Dockerfile, particularly across a team where multiple people are likely to work with the same file over time.