CodingGuidelines: describe naming rules for configuration variables
We may want to say something about command line option names in the new section as well, but for now, let's make sure everybody is clear on how to structure and name their configuration variables. The text for the rules are partly taken from the log message of Jonathan's 6b3020a2 (add: introduce add.ignoreerrors synonym for add.ignore-errors, 2010-12-01). Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jan 27, 2015 at 12:26 UTC
35840a3e789dd67528caefc146deb698bd6ac7a5
1 file changed
+23
Documentation/CodingGuidelines
+23
@@ -413,6 +413,29 @@ Error Messages
413
- Say what the error is first ("cannot open %s", not "%s: cannot open")
414
415
416
+Externally Visible Names
417
+
418
+ - For configuration variable names, follow the existing convention:
419
+
420
+ . The section name indicates the affected subsystem.
421
+
422
+ . The subsection name, if any, indicates which of an unbounded set
423
+ of things to set the value for.
424
+
425
+ . The variable name describes the effect of tweaking this knob.
426
+
427
+ The section and variable names that consist of multiple words are
428
+ formed by concatenating the words without punctuations (e.g. `-`),
429
+ and are broken using bumpyCaps in documentation as a hint to the
430
+ reader.
431
+
432
+ When choosing the variable namespace, do not use variable name for
433
+ specifying possibly unbounded set of things, most notably anything
434
+ an end user can freely come up with (e.g. branch names). Instead,
435
+ use subsection names or variable values, like the existing variable
436
+ branch.<name>.description does.
437
+
438
+
439
Writing Documentation:
440
441
Most (if not all) of the documentation pages are written in the