t1510: setup case #4

[git.git] / Documentation / CodingGuidelines

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index f628c1f3b7b706f9d585b96041e5a4b12bc0f62c..09ffc46563cba1057b37ba4a5701858fb95c5dda 100644 (file)
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -21,8 +21,13 @@ code.  For git in general, three rough rules are:
 
 As for more concrete guidelines, just imitate the existing code
 (this is a good guideline, no matter which project you are
-contributing to).  But if you must have a list of rules,
-here they are.
+contributing to). It is always preferable to match the _local_
+convention. New code added to git suite is expected to match
+the overall style of existing code. Modifications to existing
+code is expected to match the style the surrounding code already
+uses (even if it doesn't match the overall style of existing code).
+
+But if you must have a list of rules, here they are.
 
 For shell scripts specifically (not exhaustive):
 
@@ -30,21 +35,28 @@ For shell scripts specifically (not exhaustive):
    properly nests.  It should have been the way Bourne spelled
    it from day one, but unfortunately isn't.
 
- - We use ${parameter-word} and its [-=?+] siblings, and their
-   colon'ed "unset or null" form.
+ - We use POSIX compliant parameter substitutions and avoid bashisms;
+   namely:
 
- - We use ${parameter#word} and its [#%] siblings, and their
-   doubled "longest matching" form.
+   - We use ${parameter-word} and its [-=?+] siblings, and their
+     colon'ed "unset or null" form.
 
- - We use Arithmetic Expansion $(( ... )).
+   - We use ${parameter#word} and its [#%] siblings, and their
+     doubled "longest matching" form.
+
+   - No "Substring Expansion" ${parameter:offset:length}.
 
- - No "Substring Expansion" ${parameter:offset:length}.
+   - No shell arrays.
 
- - No shell arrays.
+   - No strlen ${#parameter}.
 
- - No strlen ${#parameter}.
+   - No pattern replacement ${parameter/pattern/string}.
 
- - No regexp ${parameter/pattern/string}.
+ - We use Arithmetic Expansion $(( ... )).
+
+ - Inside Arithmetic Expansion, spell shell variables with $ in front
+   of them, as some shells do not grok $((x)) while accepting $(($x))
+   just fine (e.g. dash older than 0.5.4).
 
  - We do not use Process Substitution <(list) or >(list).
 
@@ -124,3 +136,6 @@ For C programs:
    used in the git core command set (unless your command is clearly
    separate from it, such as an importer to convert random-scm-X
    repositories to git).
+
+ - When we pass <string, length> pair to functions, we should try to
+   pass them in that order.