[PATCH 3/3] CodingGuidelines: describe naming rules for configuration variables

From

Junio C Hamano <gitster@pobox.com>

Date

Jan 28, 2015, 22:33 UTC

Message-ID

<1422484393-4414-4-git-send-email-gitster@pobox.com>

In-Reply-To

<1422484393-4414-1-git-send-email-gitster@pobox.com>

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/CodingGuidelines | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 894546d..8fbac15 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -413,6 +413,31 @@ Error Messages
  - Say what the error is first ("cannot open %s", not "%s: cannot open")
 
 
+Externally Visible Names
+
+ - For configuration variable names, follow the existing convention:
+
+   . The section name indicates the affected subsystem.
+
+   . The subsection name, if any, indicates which of an unbounded set
+     of things to set the value for.
+
+   . The variable name describes the effect of tweaking this knob.
+
+   The section and variable names that consist of multiple words are
+   formed by concatenating the words without punctuations (e.g. `-`),
+   and are broken using bumpyCaps in documentation as a hint to the
+   reader.
+
+   When choosing the variable namespace, do not use variable name for
+   specifying possibly unbounded set of things, most notably anything
+   an end user can freely come up with (e.g. branch names), but also
+   large fixed set defined by the system that can grow over time
+   (e.g. what kind of common whitespace problems to notice).  Use
+   subsection names or variable values, like existing variables
+   branch.<name>.description and core.whitespace do, instead.
+
+
 Writing Documentation:
 
  Most (if not all) of the documentation pages are written in the

-- 
2.3.0-rc2-149-gdd42ee9