Editing StyleGuide (section)

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

'''[http://perldoc.perl.org/functions/my.html my]''', '''[http://perldoc.perl.org/functions/our.html our]''' and '''[http://perldoc.perl.org/functions/local.html 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 [http://perldoc.perl.org/perlpod.html POD] above them explaining the function and use of the method.
<pre>
 =pod

 =item * my_func( $var_1, %var_2 ):

 Description of function, with examples

=cut

 sub my_func
 {

 }
</pre>

=====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.
<pre>
 #########
 #
 # _my_subby( $var_1, %var_2 ):
 #
 # Description of function, with examples
 #
 sub _my_subby
 {

 }
</pre>
====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

See the [[modules]] page for full details.