Difference between revisions of "API:EPrints/StyleGuide"
(New page: <!-- 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. -...) |
|||
| Line 13: | 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->new( $opts ); | my $obj = EPrints::MyModule->new( $opts ); | ||
| − | $obj->do_thing( $thingy ); | + | $obj->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->my_sub( $arg1, [$opt_arg2], \%opts ) | + | |
| + | =item $objname = EPrints::StyleGuide->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->my_sub( "eprintid" ); | + | A description of $arg1 if needed, along with an example: |
| + | |||
| + | EPrints::StyleGuide->my_sub( "eprintid" ); | ||
| + | |||
EPrints::StyleGuide->my_sub( | EPrints::StyleGuide->my_sub( | ||
$arg1, | $arg1, | ||
| Line 87: | Line 109: | ||
opt2 => $var2, # What is var2 | opt2 => $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 --> | ||
Revision as of 18:13, 11 August 2009
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
NAME
EPrints::StyleGuide - Style guide to writing EPrints modules and code
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.
PROGRAMMING STYLE
Naming
TYPE EXAMPLE module StyleGuide subroutine get_value global var AUTH_OK local var $field_name
Subroutines
sub get_value
{
my( $self, $arg1, $arg2 ) = @_;
return $r;
}
Conditionals
if( ref($a) eq "ARRAY" )
{
return 0;
}
Loops
foreach my $field ( @fields )
{
foreach( @{$field->{ "lsd" }} )
{
$values{ $_ } = 1;
}
}
DOCUMENTATION
Name and License
Every EPrints module must start with the __LICENSE__ macro.
###################################################################### # # EPrints::StyleGuide # ###################################################################### # # __LICENSE__ # ######################################################################
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
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
{
...
}
