[GitHub] [spark] HeartSaVioR commented on a change in pull request #27577: [DOC] add config naming guideline

[GitBox <gi...@apache.org>]

HeartSaVioR commented on a change in pull request #27577: [DOC] add config naming guideline
URL: https://github.com/apache/spark/pull/27577#discussion_r379828530
 
 

 ##########
 File path: core/src/main/scala/org/apache/spark/internal/config/ConfigEntry.scala
 ##########
 @@ -17,6 +17,35 @@
 
 package org.apache.spark.internal.config
 
+// ====================================================================================
+//                      The guideline for naming configurations
+// ====================================================================================
+/*
+In general, the config name should be a noun that describes its basic purpose. It's
+recommended to add prefix to the config name to make the scope clearer. For example,
+`spark.scheduler.mode` clearly indicates that this config is for the scheduler.
+
+A config name can have multiple prefixes that are structured, which is similar to a
+qualified Java class name. Each prefix behaves like a namespace. We should only create
+a namespace if it's meaningful and can be shared by multiple configs. For example,
+`buffer.inMemoryThreshold` is preferred over `buffer.in.memory.threshold`.
+
+The followings are some best practices of naming configs for some common cases:
 
 Review comment:
   Agreed. Given we agreed upon the suggestion, it seems to just say `the best practices` or `some of the best practices`, and remove `some` in `some common cases` like @kiszk commented.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org