Line 13:

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=head_naming -->==Naming==

<!-- Pod2Wiki=head_naming -->==Naming==

−

   TYPE           EXAMPLE  

+

   TYPE           EXAMPLE

+

   module         StyleGuide

   module         StyleGuide

   subroutine     get_value

   subroutine     get_value

   global var     AUTH_OK

   global var     AUTH_OK

−

   local var      $field_name  

+

   local var      $field_name

+

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=head_subroutines -->==Subroutines==

<!-- Pod2Wiki=head_subroutines -->==Subroutines==

   sub get_value

   sub get_value

{

{

−

     my( $self, $arg1, $arg2 ) = @_;  

+

     my( $self, $arg1, $arg2 ) = @_;

+

     return $r;

     return $r;

−

}

+

}

+

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=head_conditionals -->==Conditionals==

<!-- Pod2Wiki=head_conditionals -->==Conditionals==

Line 30:

Line 34:

{

{

     return 0;

     return 0;

−

}

+

}

+

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=head_loops -->==Loops==

<!-- Pod2Wiki=head_loops -->==Loops==

Line 39:

Line 44:

       $values{ $_ } = 1;

       $values{ $_ } = 1;

}

}

−

}

+

}

+

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=head_documentation -->=DOCUMENTATION=

<!-- Pod2Wiki=head_documentation -->=DOCUMENTATION=

Line 54:

Line 60:

   # __LICENSE__

   # __LICENSE__

#

#

−

   ######################################################################  

+

   ######################################################################

+

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=head_description -->==Description==

<!-- Pod2Wiki=head_description -->==Description==

Below the license block the name, description and synopsis (a synopsis is an example of usage). Lastly the METHODS title begins the section for inline subroutine documentation.

Below the license block the name, description and synopsis (a synopsis is an example of usage). Lastly the METHODS title begins the section for inline subroutine documentation.

−

   =head1 NAME  

+

   =head1 NAME

−

   EPrints::MyModule - A one line description of MyModule  

+

−

   =head1 DESCRIPTION  

+

   EPrints::MyModule - A one line description of MyModule

−

   One or two paragraphs explaining the function of EPrints::MyModule.  

+

−

   =head1 SYNOPSIS  

+

   =head1 DESCRIPTION

−

     use EPrints::MyModule;  

+

   One or two paragraphs explaining the function of EPrints::MyModule.

+

   =head1 SYNOPSIS

+

     use EPrints::MyModule;

+

     my $obj = EPrints::MyModule-&gt;new( $opts );

     my $obj = EPrints::MyModule-&gt;new( $opts );

−

     $obj-&gt;do_thing( $thingy );  

+

     $obj-&gt;do_thing( $thingy );

−

   =head1 METHODS  

+

−

   =over 4  

+

   =head1 METHODS

−

   =cut  

+

   =over 4

+

   =cut

+

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=head_methods -->==Methods==

<!-- Pod2Wiki=head_methods -->==Methods==

Each public subroutine should have POD documentation above it, with hashes to separate it from the method above. A large module should probably be split into different sections, e.g. "CONSTRUCTOR METHODS", "ACCESSOR METHODS", etc. Private methods can be documented using Perl comments.

Each public subroutine should have POD documentation above it, with hashes to separate it from the method above. A large module should probably be split into different sections, e.g. "CONSTRUCTOR METHODS", "ACCESSOR METHODS", etc. Private methods can be documented using Perl comments.

−

   ######################################################################  

+

   ######################################################################

−

   =item $objname = EPrints::StyleGuide-&gt;my_sub( $arg1, [$opt_arg2], \%opts )  

+

   =item $objname = EPrints::StyleGuide-&gt;my_sub( $arg1, [$opt_arg2], \%opts )

+

   A description of what my_sub does and arguments it takes ($opt_arg2 is

   A description of what my_sub does and arguments it takes ($opt_arg2 is

−

   shown as optional by using brackets).  

+

   shown as optional by using brackets).

−

   A description of $arg1 if needed, along with an example:  

+

−

     EPrints::StyleGuide-&gt;my_sub( "eprintid" );  

+

   A description of $arg1 if needed, along with an example:

+

     EPrints::StyleGuide-&gt;my_sub( "eprintid" );

+

     EPrints::StyleGuide-&gt;my_sub(

     EPrints::StyleGuide-&gt;my_sub(

       $arg1,

       $arg1,

Line 87:

Line 109:

         opt2 =&gt; $var2, # What is var2

         opt2 =&gt; $var2, # What is var2

}

}

−

);

+

);

−

   Further elaboration on the effect of $var2.  

+

−

   =cut  

+

   Further elaboration on the effect of $var2.

−

   ######################################################################  

+

   =cut

+

   ######################################################################

+

   sub my_sub

   sub my_sub

{

{

...

...

−

}

+

}

+

<!-- End of Pod2Wiki -->

<!-- End of Pod2Wiki -->

<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->

<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->

API:EPrints/StyleGuide - Revision history

Tdb01r: Removing all content from page

Tdb01r at 18:13, 11 August 2009

Tdb01r: New page:

← Older revision		Revision as of 15:41, 12 August 2009
Line 1:		Line 1:
−	~~<!-- Pod2Wiki=_preamble_~~
−	~~This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.~~
−	~~-->{{Pod2Wiki}}{{API:Source\|file=EPrints/StyleGuide.pm\|package_name=EPrints::StyleGuide}}[[Category:API\|StyleGuide]]<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_name -->=NAME=~~
−	~~EPrints::StyleGuide - Style guide to writing EPrints modules and code~~

−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_description -->=DESCRIPTION=~~
−	EPrints has been under development for many years and has some fluff about the place. For new programmers this document is intended as a 'style guide' to at least keep the code and documentation consistent across new modules.
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_programming_style -->=PROGRAMMING STYLE=~~
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_naming -->==Naming==~~
−	~~TYPE EXAMPLE~~
−
−	~~module StyleGuide~~
−	~~subroutine get_value~~
−	~~global var AUTH_OK~~
−	~~local var $field_name~~
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_subroutines -->==Subroutines==~~
−	~~sub get_value~~
−	{
−	~~my( $self, $arg1, $arg2 ) = @_;~~
−
−	~~return $r;~~
−	}
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_conditionals -->==Conditionals==~~
−	~~if( ref($a) eq "ARRAY" )~~
−	{
−	~~return 0;~~
−	}
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_loops -->==Loops==~~
−	~~foreach my $field ( @fields )~~
−	{
−	~~foreach( @{$field->{ "lsd" }} )~~
−	{
−	~~$values{ $_ } = 1;~~
−	}
−	}
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_documentation -->=DOCUMENTATION=~~
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_name_and_license -->==Name and License==~~
−	~~Every EPrints module must start with the <tt>__LICENSE__</tt> macro.~~
−
−	~~######################################################################~~
−	#
−	~~# EPrints::StyleGuide~~
−	#
−	~~######################################################################~~
−	#
−	~~# __LICENSE__~~
−	#
−	~~######################################################################~~
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_description -->==Description==~~
−	~~Below the license block the name, description and synopsis (a synopsis is an example of usage). Lastly the METHODS title begins the section for inline subroutine documentation.~~
−
−	~~=head1 NAME~~
−
−	~~EPrints::MyModule - A one line description of MyModule~~
−
−	~~=head1 DESCRIPTION~~
−
−	~~One or two paragraphs explaining the function of EPrints::MyModule.~~
−
−	~~=head1 SYNOPSIS~~
−
−	~~use EPrints::MyModule;~~
−
−	~~my $obj = EPrints::MyModule->new( $opts );~~
−	~~$obj->do_thing( $thingy );~~
−
−	~~=head1 METHODS~~
−
−	~~=over 4~~
−
−	~~=cut~~
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=head_methods -->==Methods==~~
−	Each public subroutine should have POD documentation above it, with hashes to separate it from the method above. A large module should probably be split into different sections, e.g. "CONSTRUCTOR METHODS", "ACCESSOR METHODS", etc. Private methods can be documented using Perl comments.
−
−	~~######################################################################~~
−
−	~~=item $objname = EPrints::StyleGuide->my_sub( $arg1, [$opt_arg2], \%opts )~~
−
−	~~A description of what my_sub does and arguments it takes ($opt_arg2 is~~
−	~~shown as optional by using brackets).~~
−
−	~~A description of $arg1 if needed, along with an example:~~
−
−	~~EPrints::StyleGuide->my_sub( "eprintid" );~~
−
−	~~EPrints::StyleGuide->my_sub(~~
−	~~$arg1,~~
−	~~undef,~~
−	{
−	~~opt1 => $var1, # What is var1~~
−	~~opt2 => $var2, # What is var2~~
−	}
−	);
−
−	~~Further elaboration on the effect of $var2.~~
−
−	~~=cut~~
−
−	~~######################################################################~~
−
−	~~sub my_sub~~
−	{
−	~~...~~
−	}
−
−	~~<!-- End of Pod2Wiki -->~~
−	~~<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->~~