|
|
| 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 -->
| |
