diff --git a/tests/pybind11_tests.cpp b/tests/pybind11_tests.cpp
index 4646ce1e3..1d805d75b 100644
--- a/tests/pybind11_tests.cpp
+++ b/tests/pybind11_tests.cpp
@@ -10,6 +10,19 @@
 #include "pybind11_tests.h"
 #include "constructor_stats.h"
 
+/*
+For testing purposes, we define a static global variable here in a function that each individual
+test .cpp calls with its initialization lambda.  It's convenient here because we can just not
+compile some test files to disable/ignore some of the test code.
+
+It is NOT recommended as a way to use pybind11 in practice, however: the initialization order will
+be essentially random, which is okay for our test scripts (there are no dependencies between the
+individual pybind11 test .cpp files), but most likely not what you want when using pybind11
+productively.
+
+Instead, see the "How can I reduce the build time?" question in the "Frequently asked questions"
+section of the documentation for good practice on splitting binding code over multiple files.
+*/
 std::list<std::function<void(py::module &)>> &initializers() {
     static std::list<std::function<void(py::module &)>> inits;
     return inits;