###################################################################### # # EPrints::StyleGuide # ###################################################################### # # This file is part of GNU EPrints 2. # # Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ. # # EPrints 2 is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # EPrints 2 is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with EPrints 2; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # ###################################################################### package EPrints::StyleGuide; use strict; use warnings; =head1 NAME EPrints::StyleGuide - Style guide to writing EPrints modules and code =head1 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. =head1 PROGRAMMING STYLE =head2 Naming TYPE EXAMPLE module StyleGuide subroutine get_value global var AUTH_OK local var $field_name =head2 Subroutines sub get_value { my( $self, $arg1, $arg2 ) = @_; return $r; } =head2 Conditionals if( ref($a) eq "ARRAY" ) { return 0; } =head2 Loops foreach my $field ( @fields ) { foreach( @{$field->{ "lsd" }} ) { $values{ $_ } = 1; } } =head1 DOCUMENTATION =head2 Name and License Every EPrints module must start with the C<This file is part of GNU EPrints 2.> macro. Every EPrints module must start with the C<> macro. Every EPrints module must start with the C<Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ.> macro. Every EPrints module must start with the C<> macro. Every EPrints module must start with the C<EPrints 2 is free software; you can redistribute it and/or modify> macro. Every EPrints module must start with the C<it under the terms of the GNU General Public License as published by> macro. Every EPrints module must start with the C<the Free Software Foundation; either version 2 of the License, or> macro. Every EPrints module must start with the C<(at your option) any later version.> macro. Every EPrints module must start with the C<> macro. Every EPrints module must start with the C<EPrints 2 is distributed in the hope that it will be useful,> macro. Every EPrints module must start with the C<but WITHOUT ANY WARRANTY; without even the implied warranty of> macro. Every EPrints module must start with the C<MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the> macro. Every EPrints module must start with the C<GNU General Public License for more details.> macro. Every EPrints module must start with the C<> macro. Every EPrints module must start with the C<You should have received a copy of the GNU General Public License> macro. Every EPrints module must start with the C<along with EPrints 2; if not, write to the Free Software> macro. Every EPrints module must start with the C<Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA> macro. ###################################################################### # # EPrints::StyleGuide # ###################################################################### # # This file is part of GNU EPrints 2. # # Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ. # # EPrints 2 is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # EPrints 2 is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with EPrints 2; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # ###################################################################### =head2 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 =head2 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 { ... } =cut 1;