diff --git a/.flake8 b/.flake8
index ab1e14b66e..a1e2fcc1f8 100644
--- a/.flake8
+++ b/.flake8
@@ -1,12 +1,20 @@
 # -*- conf -*-
+# flake8 settings for Spack.
+#
+# Below we describe which flake8 checks Spack ignores and what the
+# rationale is.
+#
+# Let people line things up nicely:
+# - E221: multiple spaces before operator
+# - E241: multiple spaces after ‘,’
+#
+# Spack allows wildcard imports:
+# - F403: disable wildcard import
+#
+# These are required to get the package.py files to test clean.
+# - F821: undefined name (needed for cmake, configure, etc.)
+# - F999: name name be undefined or undefined from star imports.
+#
 [flake8]
-# Descriptions of ignored checks:
-#
-# E221: multiple spaces before operator
-# E241: multiple spaces after ‘,’
-# F403: disable wildcard import
-# F821: undefined name (needed for build commands)
-# F999: Undefined undefined name (needed for build commands)
-#
 ignore = E221,E241,F403,F821,F999
 max-line-length = 79