Difference between revisions of "API:EPrints/StyleGuide"

From EPrints Documentation
Jump to: navigation, search
(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-&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 -->

Revision as of 18:13, 11 August 2009

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki

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
 {
   ...
 }