CodingGuidelines Perl amendment (was: [PATCH 1/3] Add contrib/credentials/netrc with GPG support)

[Ted Zlatanov <tzz@lifelogs.com>]

On Mon, 04 Feb 2013 15:10:45 -0800 Junio C Hamano <gitster@pobox.com> wrote: 

JCH> Ted Zlatanov <tzz@lifelogs.com> writes:
JCH> I thought that we tend to avoid Emacs/Vim formatting cruft left in
JCH> the file.  Do we have any in existing file outside contrib/?
>> 
>> No, but it's a nice way to express the settings so no one is guessing
>> what the project prefers.  At least for me it's not an issue anymore,
>> since I understand your criteria better now, so let me know if you want
>> me to express it in the CodingGuidelines, in a dir-locals.el file, or
>> somewhere else.

JCH> Historically we treated this from CodingGuidelines a sufficient
JCH> clue:

JCH>     As for more concrete guidelines, just imitate the existing code
JCH>     (this is a good guideline, no matter which project you are
JCH>     contributing to). It is always preferable to match the _local_
JCH>     convention. New code added to git suite is expected to match
JCH>     the overall style of existing code. Modifications to existing
JCH>     code is expected to match the style the surrounding code already
JCH>     uses (even if it doesn't match the overall style of existing code).

JCH> but over time people wanted more specific guidelines and added
JCH> language specific style guides there.  We have sections that cover
JCH> C, shell and Python, and I do not think adding Perl would not hurt.

The following is how I have interpreted the Perl guidelines.  I hope
it's OK to include Emacs-specific settings; they make it much easier to
reindent code to be acceptable.

I will submit as a patch if you think this is reasonable at all.

The org-mode markers around the code are just a suggestion.

For Perl 5 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.

 - As in C (see above), we avoid using braces unnecessarily (but Perl
   forces braces around if/unless/else/foreach blocks, so this is not
   always possible).

 - Don't abuse statement modifiers (unless $youmust).

 - We try to avoid assignments inside if().

 - 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:

#+begin_src lisp
((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))))
#+end_src