Add a comment that subquery splicing should run last (#10181)

arangod/Aql/OptimizerRulesFeature.cpp

@@ -27,8 +27,8 @@
 #include "Basics/Exceptions.h"
 #include "Cluster/ServerState.h"
 #include "FeaturePhases/V8FeaturePhase.h"
-#include "Logger/Logger.h"
 #include "Logger/LogMacros.h"
+#include "Logger/Logger.h"
 #include "RestServer/AqlFeature.h"
 #include "StorageEngine/EngineSelectorFeature.h"
 #include "StorageEngine/StorageEngine.h"
@@ -386,6 +386,16 @@ void OptimizerRulesFeature::addRules() {
 #endif
 
   // Splice subqueries
+  //
+  // ***CAUTION***
+  // TL;DR: This rule (if activated) *must* run last.
+  //
+  // It changes the structure of the query plan by "splicing", i.e. replacing
+  // every SubqueryNode by a SubqueryStart and a SubqueryEnd node with the
+  // subquery's nodes in between, resulting in a linear query plan. If an
+  // optimizer runs after this rule, it has to be aware of SubqueryStartNode and
+  // SubqueryEndNode and would likely be more complicated to write.
+  //
   registerRule("splice-subqueries", spliceSubqueriesRule, OptimizerRule::spliceSubqueriesRule,
                OptimizerRule::makeFlags(OptimizerRule::Flags::CanBeDisabled,
                                         OptimizerRule::Flags::DisabledByDefault));