Tags:
create new tag
, view all tags

Coding Style

Best practices

  • check your code with perlcritic
  • format your code with perltidy
  • document the code with [http://perldoc.perl.org/perlpod.html POD]
  • mark deprecated code in your library

Documentig classes and modules with POD

Header

Put general information about the class at the beginning of the file.

Example:

#!/usr/bin/perl

# RCS information
# enable substitution with:
#| |  $ svn propset svn:keywords "Id Revision HeadURL Source Date"
#
#| |  $Id$
#| |  $Revision$
#| |  $HeadURL$
#| |  $Date$
#

=head1 NAME

module name - short comment

=head1 SYNOPSIS

=head1 DESCRIPTION

=cut

use strict;
use warnings;

Code

Document methods and subroutines near the code

Example

=head1 SUBROUTINES/METHODS

=over 1



=item foo()

Short description

=over 2

=item Usage     : my @a = foo( $arg );

=item Purpose   : description

=item Returns   : array of L<Some::Object>

=item Arguments : $arg : argument description

=item Throws    : dies if ...

=item Comments  : general comments

=item See also  : L<Some::Other::Class>

=back

=cut

sub foo {

  ...

}

Minimal Example

Since programmers tend to be lazy, and because a minimalistic documentation is still better than none:


=item foo()

Short description

=back

sub foo {

  ...


}

Footer

Put licensing and contact information at the end of the file

Example


1;

__END__

=pod

=head1 BUGS AND LIMITATIONS

There are no known bugs in this module.
Please report problems to Matteo Corti (corti@ethz.ch) or Swen Vermeul (swen@ethz.ch)

Patches are welcome.

=head1 AUTHOR

Swen Vermeul (swen@ethz.ch)
Matteo Corti (corti@ethz.ch)

=head1 LICENCE AND COPYRIGHT

Copyright (c) Informatikdienste ETH Zurich. All rights reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

Deprecated code

To warn the users of your modules that a subroutine is obsolete mark it with the deprecated attribute. Remember to mark it as deprecated in the documentation as well.

Example:

package SomeObj;

use Attribute::Deprecated;


=item do_something_obsolete()

Short description

=over 2

=item Usage     : my @a = foo( $arg );
[...]
=item Deprecated : use L<my_nice_new_function> instead

=back

=cut

sub do_something_obsolete : Deprecated {
  ...
}

Hints

perltidy and long lines

If you want to keep long lines (as in the case of :ATTR declarations) you can enclose the code with `#<<<` and `#>>>`. Example:

#<<<
my %name_of :ATTR( :get<name    :set<name>   :init_arg<name>   :default<untitled> );
#>>>

Networking

On our Machines there are several network interfaces configured with different IP addresses on different subnets.

When establishing a new connection Perl automatically chooses one of them (usually eth0 on Linux) and uses the interface IP address.

If the other peer has an IP filter we will be most likely blocked since we will be using a "random" IP address.

To avoid this when connecting we should instruct perl to bind to the right network interace (i.e., the one with idn's IP address).

Config

The FQDN of the instance (e.g., idn.ethz.ch or idnt.ethz.ch) is a condiguration parameter in the Network section:

[Network]

name : idn.ethz.ch

Low level Perl

You can use bind to select the IP address for a socket:

bind SOCKET,NAME
        Binds a network address to a socket, just as the bind system call does. | Returns true if
|  |  |  |  it succeeded, false otherwise. | NAME should be a packed address of the appropriate type
|  |  |  |  for the socket. | See the examples in "Sockets: Client/Server Communication" in perlipc.

Net::SSH::Perl

The address is specified in the options array:

use Net::SSH::Perl;
my $ssh = Net::SSH::Perl->new(
    'example org',| 
    options => [ "BindAddress| $Basis::config->{Network}{name}"| ],
);

Command line ssh

You can use the `-b` option

$cmd = "ssh -b| $Basis::config->{Network}{name}| -l user example.org"

LWP

The bind address is specified through the `EXTRA_SOCK_OPTS` variable:

no warnings 'once';
@LWP::Protocol::http::EXTRA_SOCK_OPTS = ( !LocalAddr => $Basis::config->{Network}{name} );

-- SwenVermeul - 2015-06-09

Topic revision: r1 - 2015-06-09 - vermeul
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback