Update CodingGuidelines for Perl

Add the coding guidelines for Perl.

Signed-off-by: Ted Zlatanov <tzz@lifelogs.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 69f7e9b76c3f9b87b7951fb0df6a9720edadeb3e..4f384e58f1a5339f1ee7ab6057b330d4aa550479 100644 (file)
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -18,6 +18,7 @@ code.  For git in general, three rough rules are:
    judgement call, the decision based more on real world
    constraints people face than what the paper standard says.
 
    judgement call, the decision based more on real world
    constraints people face than what the paper standard says.
 

+Make your code readable and sensible, and don't try to be clever.

 
 As for more concrete guidelines, just imitate the existing code
 (this is a good guideline, no matter which project you are
 
 As for more concrete guidelines, just imitate the existing code
 (this is a good guideline, no matter which project you are


@@ -179,6 +180,47 @@ For C programs:
  - Use Git's gettext wrappers to make the user interface
    translatable. See "Marking strings for translation" in po/README.
 
  - Use Git's gettext wrappers to make the user interface
    translatable. See "Marking strings for translation" in po/README.
 

+For Perl programs:
+
+ - Most of the C guidelines above apply.
+
+ - We try to support Perl 5.8 and later ("use Perl 5.008").
+
+ - use strict and use warnings are strongly preferred.
+
+ - Don't overuse statement modifiers unless using them makes the
+   result easier to follow.
+
+       ... do something ...
+       do_this() unless (condition);
+        ... do something else ...
+
+   is more readable than:
+
+       ... do something ...
+       unless (condition) {
+               do_this();
+       }
+        ... do something else ...
+
+   *only* when the condition is so rare that do_this() will be almost
+   always called.
+
+ - We try to avoid assignments inside "if ()" conditions.
+
+ - Learn and use Git.pm if you need that functionality.
+
+ - For Emacs, it's useful to put the following in
+   GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
+
+    ;; note the first part is useful for C editing, too
+    ((nil . ((indent-tabs-mode . t)
+                  (tab-width . 8)
+                  (fill-column . 80)))
+     (cperl-mode . ((cperl-indent-level . 8)
+                    (cperl-extra-newline-before-brace . nil)
+                    (cperl-merge-trailing-else . t))))
+

 Writing Documentation:
 
  Every user-visible change should be reflected in the documentation.
 Writing Documentation:
 
  Every user-visible change should be reflected in the documentation.