standard perl program representation

I want standard way of perl programming. i am writing perl scripts but i need to write some information before program starts. what is the purpose of this sript and organization and time and date and file location ...e.t.c. for example in c language we are writting like this

  /*!
 *****************************************************************************
 *
 * @file code.c
 * @brief
 * @b Description: temperature measurement
 * @ university of east london, All rights reserved.
 *
 * $Header: //data/name/source/code.c#10 $
 * $DateTime: 开发者_运维技巧2011/01/18 16:06:25 $
 *
 ****************************************************************************/
 /* Include files:                                                           */
 #include "stdio.h"

as like above ,comments is used in c language. i need to write same description before perl script. is there any format. i am very beginer to perl.

---

I user perl's inbuilt documention thing. pod

http://perldoc.perl.org/perlpod.html

A sample simple class I'd write is

#!/bin/perl
#---------------------------------------------------------------------------------
=head1 Temperature.pm

This class records temperatures ant converts between celcius and ferenheit

university of east london, All rights reserved.

    $Id$
    $Url$

=head2 Constants

=over

=item Temperature units

These constants are used to indicate the units temperature is recorded in.

=cut
#---------------------------------------------------------------------------------
use constant UNIT_CELSUIS   => 1;
use constant UNIT_FARENHEIT => 2;

#---------------------------------------------------------------------------------
=item Attribute indexes

Our object is an array ref, so these private constants are the indexes
of the attributes of our class

=cut
#---------------------------------------------------------------------------------
my $IDX_DEGREES = 0;
my $IDX_UNITS   = 1;

#---------------------------------------------------------------------------------
=back

=head2 Methods

=over

=item new

This is the constructor creates the object. Default is 0 degrees celsius

=cut
#---------------------------------------------------------------------------------
sub new
{
    my( $class, $degrees, $units ) = @_;
    my $self = bless( [], ref($class) || $class );
    $self->[$IDX_DEGREES] = $degrees || 0;
    $self->[$IDX_UNITS]   = $units   || UNIT_CELSIUS;
    return $self;
} # END new

#---------------------------------------------------------------------------------
=item asCelsius

Returns the temperature in degrees celsius

=cut
#---------------------------------------------------------------------------------
sub asCelsius
{
    my( $self ) = @_;
    if( $self->[$IDX_UNITS] == UNIT_CELSIUS )
    {
        return $self->[$IDX_DEGREES];
    }
    else
    {
        return ( $self->[$IDX_DEGREES]  − 32 ) * (5⁄9);
    }
} # END as Celsius

#---------------------------------------------------------------------------------
=back

End of module

=cut
#---------------------------------------------------------------------------------
1;

---

There's actually a standard in Perl for embedding documentation in your script, but it's not what you think. Take a look at Perl's POD format. This is the standard way documentation is embedded in a Perl program. You can use the perldoc program to see this documentation:

$ perldoc myscript.pl

And, you can use the various pod2xxx commands to format this information:

$ pod2html myscript.pl > myscript.html  #HTML format
$ pod2text myscript.pl > myscript.txt   #Text format
$ pod2wiki myscript.pl > wikitext.txt   #For embedding into various Wikis (not part of std Perl dist)

The POD format is pretty simple and easy to learn. The most difficult thing to understand is that you must have a blank line between each command and section.

This is wrong:

 =pod
 =head1 PROGRAM NAME
 myscript.pl
 =head1 DESCRIPTION
 My Program is nice.
 =head1 SYNOPSIS
 My program does things

Instead:

 =pod

 =head1 PROGRAM NAME

 myscript.pl

 =head1 DESCRIPTION

 My Program is nice.

 =head1 SYNOPSIS

 My program does things

See also Pod Style and Pod Spec.

All information you see in the CPAN page is generated by the POD embedded in the modules. Same with ActiveState's ActivePerl documentation.

POD format is usually in the same format as MANPAGES. So you would have the following sections as =head1:

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• SEE ALSO
• BUGS
• AUTHOR
• COPYRIGHT

On top of that, I also tend to embed a $USAGE variable that gives shows how the command is used:

my $USAGE =<<USAGE;
    myscript.pl -foo <foo> [-bar <bar>] <barfoo>

    or

    myscript.pl -help
USAGE

[...]

if ($help) {
   say $USAGE;
   exit 0;
}

However, this really isn't necessary since you can use the Pod::Usage module (which is part of the standard Perl distribution) to print out the SYNOPSIS section of our Pod document anyway.

---

What about POD ( or see perldoc )?

It is pretty much standard in the Perl community and in my experience it is a nice and consistent way to document scripts as well as modules.

---

In my experience, this is not a common practice in the Perl world, so, no, there isn't any format that I can tell you to use. It's easy enough to use your existing format with only minor modifications, though:

#!/usr/bin/env perl

 #############################################################################
 #
 # @file code.c
 # @brief
 # @b Description: temperature measurement
 # @ university of east london, All rights reserved.
 #
 # $Header: //data/name/source/code.c#10 $
 # $DateTime: 2011/01/18 16:06:25 $
 #
 #############################################################################

use strict;
use warnings;

Note that Perl doesn't have block comments as such, but line comments fit with your existing format anyhow. Also remember that the #! line, if present, needs to be the absolutely first line of the file or else it won't do anything.