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. -...)
 
(Removing all content from page)
 
(One intermediate revision by the same user not shown)
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-&gt;{ "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-&gt;new( $opts );
 
    $obj-&gt;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-&gt;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-&gt;my_sub( "eprintid" ); 
 
    EPrints::StyleGuide-&gt;my_sub(
 
      $arg1,
 
      undef,
 
      {
 
        opt1 =&gt; $var1, # What is var1
 
        opt2 =&gt; $var2, # What is var2
 
      }
 
    ); 
 
  Further elaboration on the effect of $var2. 
 
  =cut 
 
  ###################################################################### 
 
  sub my_sub
 
  {
 
    ...
 
  } 
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
 

Latest revision as of 15:41, 12 August 2009