From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 14 Feb 2013 18:28:55 +0000 (-0800)
Subject: Merge branch 'tz/perl-styles'
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=07203d6b6cde4f084f5977e2a781f8194d6cb581;p=git.git

Merge branch 'tz/perl-styles'

Add coding guidelines for writing Perl scripts for Git.

* tz/perl-styles:
  Update CodingGuidelines for Perl
---

07203d6b6cde4f084f5977e2a781f8194d6cb581
diff --cc Documentation/CodingGuidelines
index 9eb2d9fe7,4f384e58f..b1bfff630
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@@ -179,20 -180,47 +180,61 @@@ For C programs
   - 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))))
+ 
 +For Python scripts:
 +
 + - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
 +
 + - As a minimum, we aim to be compatible with Python 2.6 and 2.7.
 +
 + - Where required libraries do not restrict us to Python 2, we try to
 +   also be compatible with Python 3.1 and later.
 +
 + - When you must differentiate between Unicode literals and byte string
 +   literals, it is OK to use the 'b' prefix.  Even though the Python
 +   documentation for version 2.6 does not mention this prefix, it has
 +   been supported since version 2.6.0.
 +
  Writing Documentation:
  
   Every user-visible change should be reflected in the documentation.