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>
Ted Zlatanov committed
Feb 6, 2013 at 14:49 UTC
c5e366b1f8dd72d7516cf0029fd4bb1a7ec616a9
1 file changed
+42
Documentation/CodingGuidelines
+42
@@ -18,6 +18,7 @@ code. For git in general, three rough rules are:
18
judgement call, the decision based more on real world
19
constraints people face than what the paper standard says.
20
21
+Make your code readable and sensible, and don't try to be clever.
22
23
As for more concrete guidelines, just imitate the existing code
24
(this is a good guideline, no matter which project you are
@@ -179,6 +180,47 @@ For C programs:
180
- Use Git's gettext wrappers to make the user interface
181
translatable. See "Marking strings for translation" in po/README.
182
183
+For Perl programs:
184
+
185
+ - Most of the C guidelines above apply.
186
+
187
+ - We try to support Perl 5.8 and later ("use Perl 5.008").
188
+
189
+ - use strict and use warnings are strongly preferred.
190
+
191
+ - Don't overuse statement modifiers unless using them makes the
192
+ result easier to follow.
193
+
194
+ ... do something ...
195
+ do_this() unless (condition);
196
+ ... do something else ...
197
+
198
+ is more readable than:
199
+
200
+ ... do something ...
201
+ unless (condition) {
202
+ do_this();
203
+ }
204
+ ... do something else ...
205
+
206
+ *only* when the condition is so rare that do_this() will be almost
207
+ always called.
208
+
209
+ - We try to avoid assignments inside "if ()" conditions.
210
+
211
+ - Learn and use Git.pm if you need that functionality.
212
+
213
+ - For Emacs, it's useful to put the following in
214
+ GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
215
+
216
+ ;; note the first part is useful for C editing, too
217
+ ((nil . ((indent-tabs-mode . t)
218
+ (tab-width . 8)
219
+ (fill-column . 80)))
220
+ (cperl-mode . ((cperl-indent-level . 8)
221
+ (cperl-extra-newline-before-brace . nil)
222
+ (cperl-merge-trailing-else . t))))
223
+
224
Writing Documentation:
225
226
Every user-visible change should be reflected in the documentation.