[Nagiosplug-devel] Perl guidelines

[Andreas Ericsson]

Ton Voon wrote:
> Andreas,
> 
> This makes sense to add. I don't think you need permission as I think 
> the whole Perl book is generated from the perldoc supplied with perl and 
> that is under an Artistic or GPL license. Since you have credited the 
> original source, that should be sufficient. In CVS now.
> 

The book isn't autogenerated, so I actually did need permission, but I 
got it so that doesn't matter anyway. Just thought I'd let you know.

> While we are talking about guidelines, what about following our 
> developer guidelines (section 8.1):
> 
> Patches should be submitted via  SourceForge's  tracker system for 
> Nagiosplug patches and be announced to the nagiosplug-devel mailing list.
> 

I get 2 second rta's to sourceforge frequently, so I try to use it as 
little as possible. Sorry about that.

> :)
> 
> Ton
> 
> 
> On 19 Nov 2004, at 11:42, Andreas Ericsson wrote:
> 
>> Perl scripts lack uniform guidelines as to their indentation and 
>> coding styles. I've written up some to be included in the CODING 
>> document distributed with the CVS distribution. The text is borrowed 
>> (with modifications) from the O'Reilly book "Programming Perl".
>>
>> I have just now written O'Reilly asking permission to include the text.
>>
>> Patch included against latest CVS.
>>
>> -- 
>> Andreas Ericsson                   andreas.ericsson at op5.se
>> OP5 AB                             www.op5.se
>> Lead Developer
>> Index: CODING
>> ===================================================================
>> RCS file: /cvsroot/nagiosplug/nagiosplug/CODING,v
>> retrieving revision 1.2
>> diff -u -r1.2 CODING
>> --- CODING    9 Feb 2003 12:54:01 -0000    1.2
>> +++ CODING    19 Nov 2004 11:42:07 -0000
>> @@ -2,7 +2,9 @@
>>  code that is consistent with the existing core plugins.
>>
>>  The primary goals of these standards are internal consistency, and
>> -readability in a wide range of environments.
>> +readability in a wide range of environments, as well as the mental 
>> welfare
>> +of plugin developers.
>> +
>>
>>  1. C Language Programming
>>
>> @@ -33,6 +35,83 @@
>>  e) The opening brace of an if or while block is on the same line as
>>  the end of the conditional expression (the '-br' option).
>>
>> +
>>  2. Perl Language Programming
>>
>> -<To Be Written>
>> +Taken from the O'Reilly book "Programming Perl" (3rd edition, pages 
>> 604-606) with
>> +modifications for clarity and to cohere with C coding standards.
>> +
>> +*) Always check the return code of system calls.
>> +
>> +a) Use tab indentation.
>> +
>> +b) Put space before the opening brace of a multiline block.
>> +
>> +c) A short block may be put on one line, including braces.
>> +
>> +d) Never omit the semicolon.
>> +
>> +e)  Surround most operators with space.
>> +
>> +    $x = 5;    # do this
>> +    $y=5;      # don't do this
>> +
>> +f) Surround a "complex" subscript (inside brackets) with space.
>> +
>> +g) Put empty lines between chunks of code that do different things.
>> +
>> +*) Always check the return code of system calls.
>> +
>> +h) Put a newline between closing brace and else or elsif.
>> +
>> +i) Do not put space between a function name and its opening parenthesis.
>> +
>> +j) Do not put space before a semicolon.
>> +
>> +k) Put space after each comma.
>> +
>> +l) Break long lines after an operator (but before 'and' and 'or', 
>> even when
>> +spelled as && and ||)).
>> +
>> +*) Always check the return code of system calls.
>> +
>> +m) Line up corresponding items vertically.
>> +
>> +n) Use redundant parentheses only where it increases readability.
>> +
>> +o) An opening brace should be put on the same line as its preceding 
>> keyword,
>> +if  possible; otherwise, line them up vertically.
>> +
>> +    while ($condition) {
>> +        # do something
>> +    }
>> +
>> +    while ($this_condition and $that_condition and $some_other_condition
>> +           and $this_really_really_really_long_condition)
>> +    {
>> +        # do something
>> +    }
>> +
>> +p) Do things the most readable way. For instance:
>> +
>> +    open(FOO, $foo) or die "Can't open $foo: $!";
>> +
>> +is  better than
>> +
>> +    die "Can't open $foo: $!" unless open(FOO, $foo);
>> +
>> +because the second way hides the main point of the statement in a 
>> modifier.
>> +
>> +q) Just because an operator lets you assume default arguments doesn't 
>> mean
>> +that you should always use them. The defaults are there for lazy 
>> programmers
>> +writing one-shot, non-shared programs. If you want your program to be 
>> readable,
>> +consider supplying the argument.
>> +
>> +r) Choose mnemonic identifiers. That is, don't name your variables 
>> $h, $c
>> +and $w. Try $hostaddress, $critical and $warning instead ($host, 
>> $crit and
>> +$warn is OK too).
>> +
>> +s) Use underscore to split words in long identifiers. That is, use
>> +$service_port instead of $ServicePort as the former is much more 
>> readable.
>> +
>> +*) Always check the return code of system calls.
> 
> 

-- 
Andreas Ericsson                   andreas.ericsson at op5.se
OP5 AB                             www.op5.se
Lead Developer