Add comments

main-settings/src/main/scala/sbt/Project.scala

@@ -337,6 +337,8 @@ object Project:
     [a] => (k: ScopedKey[a]) => ScopedKey(f(k.scope), k.key)
 
   def transform(g: Scope => Scope, ss: Seq[Def.Setting[?]]): Seq[Def.Setting[?]] =
+    // We use caching to avoid creating new Scope instances too many times
+    // Creating a new Scope is CPU expensive because of the uniqueness cache
     val f = mapScope(Util.withCaching(g))
     ss.map(_.mapKey(f).mapReferenced(f))
 

main-settings/src/main/scala/sbt/Scope.scala

@@ -23,6 +23,8 @@ final case class Scope private (
     task: ScopeAxis[AttributeKey[?]],
     extra: ScopeAxis[AttributeMap]
 ):
+  // Since we use a uniqueness cache we can pre-compute the hashCode for free
+  // It is always going to be used at least once
   override val hashCode = ScalaRunTime._hashCode(this)
 
   def rescope(project: Reference): Scope = copy(project = Select(project))
@@ -43,6 +45,9 @@ final case class Scope private (
 end Scope
 
 object Scope:
+  // We use a global uniqueness cache to avoid duplicating Scope.
+  // At the time of writing, it divides the number of long-living instances by 15
+  // reducing the pressure on the heap, and speed up the loading.
   private val uniquenessCache = TrieMap.empty[Scope, Scope]
 
   def apply(

main/src/main/scala/sbt/internal/Load.scala

@@ -274,6 +274,8 @@ private[sbt] object Load {
       finalTransforms(settings0)
     }
     val delegates = timed("Load.apply: config.delegates", log) {
+      // We use caching to avoid creating new Scope instances too many times
+      // Creating a new Scope is CPU expensive because of the uniqueness cache
       Util.withCaching(config.delegates(loaded))
     }
     val (cMap, data) = timed("Load.apply: Def.make(settings)...", log) {