StyleGuide

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

It helps if all things are written in a consistent style: when one looks at code, we recognise things by the format of the name:

Global Variables

Global variables are variables that are in scope for the entire system, not restricted to specific user sessions. Examples of Global Variables are the AUTH_OK code returned by the Apache web server subsystem.

EPrints follows the general Perl convention, and such variables (and CONSTANTS) should be in CAPITAL LETTERS

As a general rule code outside the core should not really be creating global variables, however there are situations

            AUTH_OK = "1";
            

Local Variables

Variables in code must always be pre-declared, and should be given the most appropriate level of restriction

my, our and local variables are all available to you, however we really really suggest you use my variables wherever possible.

Local variables should be given names that reflect their content ($authenticated) rather than a short nmenonic ($au). Local variables should be underscore seperated ($current_password), not camelCased ($currentPassword)

'The appropriate length of a name is inversely proportional to the size of its scope.' --Mark-Jason Dominus 'Choose mnemonic identifiers. If you can't remember what mnemonic means, you've got a problem.' -- Larry Wall

Preferred technique:

 my $proxy_depositor;
 $proxy_depositor = get_proxy_depositor($session, $eprint);

Acceptable technicque:

 my $proxy_depositor = get_proxy_depositor($session, $eprint);

Subroutines

Subroutines (aka functions, aka methods) should also be underscore seperated

Public methods

These are the API calls that are used to interact with your code.

Public methods must start with a lowe-case letter [a-z], and are required to have POD above them explaining the function and use of the method.

Private methods

Private functions are the subroutines in your modules that people should not be using. Private functions should start with an underscore, and have simple perl comments above them, explaining the function of the subroutine.

Modules

Modules (aka packages) are the file that contains the collection of methods & private funtions that makes your code do whatever it does.

Modules are named in the perl style: Perl informally reserves lowercase module names for pragma modules like integer and strict. Other modules should begin with a capital letter and use mixed case

    package EPrints::Plugin::Sword::Import::FiddleDeeDee

Subroutines

This applies to all subroutines - public or private.

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

                     return $r;
             }

Where possible, use "return" rather than an "if" block.

AVOID:

             sub get_value
             {
                     my( $self, $arg1 ) = @_;

                     my $r;
                     if( $arg1 )
                     {
                             $r = $arg1 * 2;
                     }
                     else
                     {
                             log( "some error" );
                     }
                     
                     return $r;
             }

Prefer this style instead, treating the problem like a basic exception to the normal running of the function:

             sub get_value
             {
                     my( $self, $arg1 ) = @_;

                     if( !defined $arg1 )
                     {
                            log( "some error" );
                            return;
                     }
     
                     return $arg1 * 2;
             }

Conditionals

             if( ref($a) eq "ARRAY" )
             {
                     print "Dang";
                     return 0;
             }

If the code inside the condition this is acceptable:

             return 0 if( ref($a) eq "ARRAY" );

             $a = 23 if( !defined $a );

However this is NEVER OK:

             if( !defined $a ) $a = 23;

Loops

             foreach my $field ( @fields )
             {
                     push @foo, $field->get_name();
             }

OR, when nested:

             FIELD: foreach my $field ( @fields )
             { 
                     VALUE: foreach my $value ( @{$field->{ "lsd" }} )
                     {
                             next VALUE if !defined $value; 
                             $values{ $value } = 1;
                     }
             }

Avoid $_ where possible, it is just confusing to everyone else (and has a tendency to be written over by Lazy Programmers)

Try and use "next" rather than if when inside loops.

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

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

Automatically reformatting code

There is a wonderful utility called perltidy (find link)

This reformats perl for you (and does a syntax check at the same time... lovely.

Use:

 perltidy -gnu -csc -b JSON.pm

 -gnu reformats into the general 'gnu' style (as opposed to the "Larry Wall/Perl" style)
 -csc adds comments to the end of longish loops
 -b edits the file in place (so you may want to leave that off initially)