docs: say "commits" in the --depth option wording for git-clone
[gitweb.git] / Documentation / CodingGuidelines
index b99fa87f6853775c6c021de2fab1c320e5175561..f4137c68ff80647644cc1f3d45d24457f505e2a0 100644 (file)
@@ -126,6 +126,17 @@ For C programs:
    "char * string".  This makes it easier to understand code
    like "char *string, c;".
 
+ - Use whitespace around operators and keywords, but not inside
+   parentheses and not around functions. So:
+
+        while (condition)
+               func(bar + 1);
+
+   and not:
+
+        while( condition )
+               func (bar+1);
+
  - We avoid using braces unnecessarily.  I.e.
 
        if (bla) {
@@ -153,6 +164,16 @@ For C programs:
         * multi-line comment.
         */
 
+   Note however that a comment that explains a translatable string to
+   translators uses a convention of starting with a magic token
+   "TRANSLATORS: " immediately after the opening delimiter, even when
+   it spans multiple lines.  We do not add an asterisk at the beginning
+   of each line, either.  E.g.
+
+       /* TRANSLATORS: here is a comment that explains the string
+          to be translated, that follows immediately after it */
+       _("Here is a translatable string explained by the above.");
+
  - Double negation is often harder to understand than no negation
    at all.
 
@@ -243,6 +264,15 @@ For Python scripts:
    documentation for version 2.6 does not mention this prefix, it has
    been supported since version 2.6.0.
 
+Error Messages
+
+ - Do not end error messages with a full stop.
+
+ - Do not capitalize ("unable to open %s", not "Unable to open %s")
+
+ - Say what the error is first ("cannot open %s", not "%s: cannot open")
+
+
 Writing Documentation:
 
  Most (if not all) of the documentation pages are written in the