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

From: Ted Zlatanov <tzz@lifelogs.com>
Date: Feb 6, 2013, 15:10 UTC
Message-ID: <871ucto4vj.fsf_-_@lifelogs.com>
In-Reply-To: <7v7gmn1xqi.fsf@alter.siamese.dyndns.org>

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/?

Show 6 quoted lines

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