Comment Warnings

Comment warnings flag .env.example keys that lack a documenting comment. A well documented .env.example is the fastest onboarding for a new contributor. This check is opt-in and off by default.

What Counts as Documented

A key is documented when either:

  • it has an inline # comment after the value, or
  • a real # comment sits in the run of comment lines directly above it.
.env.example 
# Stripe webhook signing secret
STRIPE_WEBHOOK_SECRET=      # documented (comment above)
PORT=3000 # server port     # documented (inline comment)
API_KEY=                    # reported (undocumented)

Rules

  • The comment must be directly above the key, or inline after the value.
  • A blank line ends the run — a comment above a blank line does not document the key below it.
  • @expire annotation lines are transparent: a bare # @expire 2026-12-31 is not documentation on its own, but a real comment above it still documents the key.
  • A shared section header such as # === Database === counts only for the first key directly beneath it — keys further down are still reported.
.env.example 
# API key for the billing service, rotated quarterly.
# @expire 2026-12-31
API_KEY=                    # documented (comment above the annotation)

Enable / Disable

Off by default. Enable it via CLI:

CLI
dotenv-diff --comment-warnings

Or in dotenv-diff.config.json:

dotenv-diff.config.json 
{
  "commentWarnings": true
}

See also

← Optional Keys Writing a Good .env.example →