stas 01/09/17 06:13:05
Added: src/devel/modperl_style modperl_style.pod
Log:
- ported the original modperl_style.pod from pod/modperl_style.pod
- added a few style and coding guidelines
Revision Changes Path
1.1 modperl-docs/src/devel/modperl_style/modperl_style.pod
Index: modperl_style.pod
===================================================================
=head1 mod_perl Code Development Style Guide
=head1 Coding Style Guide
We try hard to code mod_perl using an identical style. Because
everyone in the team should be able to read and understand the code as
quickly and easily as possible. Some will have to adjust their habits
for the benefit of all.
=over 4
=item * C code
mod_perl's C code follows the Apache style guide:
http://dev.apache.org/styleguide.html
=item * XS code
C code inside XS modules also follows the Apache style guide.
=item * Perl code
mod_perl's Perl code also follows the Apache style guide, in terms of
indentation, braces, etc. Style issues not covered by Apache style of
guide should be looked up in the I<perlstyle> manpage.
=back
Here are the rough guidelines with more stress on the Perl coding
style.
=over 4
=item Indentation
Do use 4 characters indentation.
emacs: cperl-mode: .xemacs/custom.el
(custom-set-variables
'(cperl-indent-level 4)
'(cperl-continued-statement-offset 4)
)
vi: ???
=item Tabs
Do NOT use tabs.
emacs: cperl-mode: .xemacs/custom.el
(custom-set-variables
'(cperl-tab-always-indent t)
'(indent-tabs-mode nil)
)
vi: ???
=item Block Braces
Do use a style similar to K&R style, not the same. The following
example is the best guide:
Do:
sub foo {
my ($self, $cond, $baz, $taz) = @_;
if ($cond) {
bar();
}
else {
$self->foo("one", 2, "...");
}
return $self;
}
Don't:
sub foo
{
my ($self,$bar,$baz,$taz)=@_;
if( $cond )
{
&bar();
} else { $self->foo ("one",2,"..."); }
return $self;
}
=item Lists and Arrays
Whenever you create a list or an array, always add a comma after the
last item. The reason for doing this is that it's highly probable that
new items will be appended to the end of the list in the future. If
the comma is missing and this isn't noticed, there will be an error.
Do:
my @list = (
"item1",
"item2",
"item3",
);
Don't:
my @list = (
"item1",
"item2",
"item3"
);
=item Last Statement in the Block
The same goes for C<;> in the last statement of the block. Almost
always add it even if it's not required, so when you add a new
statement you don't have to remember to add C<;> on a previous line.
Do:0
sub foo {
statement1;
statement2;
statement3;
}
Don't
sub foo {
statement1;
statement2;
statement3
}
=back
=head1 Function and Variable Prefixes Convention
=over 4
=item modperl_
The prefix for mod_perl C API functions.
=item MP_
The prefix for mod_perl C macros.
=item mpxs_
The prefix for mod_perl XS utility functions.
=item mp_xs_
The prefix for mod_perl I<generated> XS utility functions.
=item MPXS_
The prefix for mod_perl XSUBs with an XS() prototype.
=back
=head1 Coding Guidelines
The following are the Perl coding guidelines:
=head2 Global Variables
=over 4
=item avoid globals in general
=item avoid $&, $', $`
See C<Devel::SawAmpersand>'s I<README> that explains the evilness.
Under mod_perl everybody suffers when one is seen anywhere since the
interpreter is never shutdown.
=back
=head2 Modules
=over 4
=item Exporting/Importing
Avoid too much exporting/importing (glob aliases eat up memory)
When you do wish to import from a module try to use an explicit list or
tag whenever possible, e.g.:
use POSIX qw(strftime);
When you do not wish to import from a module, always use an empty list
to avoid any import, e.g.:
use IO::File ();
(explain how to use Apache::Status to find imported/exported
functions)
=back
=head2 Methods
=over 4
=item indirect vs direct method calls
Avoid indirect method calls, e.g.
Do:
CGI::Cookie->new
Don't:
new CGI::Cookie
=back
=head2 Inheritance
=over 4
=item Avoid inheriting from certain modules
Exporter.
To avoid inheriting B<AutoLoader::AUTOLOAD>
Do:
*import = \&Exporter::import;
Don't:
@MyClass::ISA = qw(Exporter);
=back
=head2 Symbol tables
=over 4
=item %main::
stay away from C<main::> to avoid namespace clashes
=back
=head2 Use of $_ in loops
Avoid using C<$_> in loops unless it's a short loop and you don't call
any subs from within the loop. If the loop started as short and then
started to grow make sure to remove the use of C<$_>:
Do:
for my $idx (1..100) {
....more than few lines...
foo($idx);
....
}
Don't:
for (1..100) {
....more than a few statements...
foo();
....
}
Because foo() might change C<$_> if foo()'s author didn't localize C<$_>.
This is OK:
for (1..100) {
.... a few statements with no subs called
# do something with $_
....
}
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
Stas Bekman E<lt>stas@stason.orgE<gt>
=head1 Authors
Stas Bekman E<lt>stas@stason.orgE<gt>
Doug MacEachern
=cut
Added: src/devel/modperl_style modperl_style.pod
Log:
- ported the original modperl_style.pod from pod/modperl_style.pod
- added a few style and coding guidelines
Revision Changes Path
1.1 modperl-docs/src/devel/modperl_style/modperl_style.pod
Index: modperl_style.pod
===================================================================
=head1 mod_perl Code Development Style Guide
=head1 Coding Style Guide
We try hard to code mod_perl using an identical style. Because
everyone in the team should be able to read and understand the code as
quickly and easily as possible. Some will have to adjust their habits
for the benefit of all.
=over 4
=item * C code
mod_perl's C code follows the Apache style guide:
http://dev.apache.org/styleguide.html
=item * XS code
C code inside XS modules also follows the Apache style guide.
=item * Perl code
mod_perl's Perl code also follows the Apache style guide, in terms of
indentation, braces, etc. Style issues not covered by Apache style of
guide should be looked up in the I<perlstyle> manpage.
=back
Here are the rough guidelines with more stress on the Perl coding
style.
=over 4
=item Indentation
Do use 4 characters indentation.
emacs: cperl-mode: .xemacs/custom.el
(custom-set-variables
'(cperl-indent-level 4)
'(cperl-continued-statement-offset 4)
)
vi: ???
=item Tabs
Do NOT use tabs.
emacs: cperl-mode: .xemacs/custom.el
(custom-set-variables
'(cperl-tab-always-indent t)
'(indent-tabs-mode nil)
)
vi: ???
=item Block Braces
Do use a style similar to K&R style, not the same. The following
example is the best guide:
Do:
sub foo {
my ($self, $cond, $baz, $taz) = @_;
if ($cond) {
bar();
}
else {
$self->foo("one", 2, "...");
}
return $self;
}
Don't:
sub foo
{
my ($self,$bar,$baz,$taz)=@_;
if( $cond )
{
&bar();
} else { $self->foo ("one",2,"..."); }
return $self;
}
=item Lists and Arrays
Whenever you create a list or an array, always add a comma after the
last item. The reason for doing this is that it's highly probable that
new items will be appended to the end of the list in the future. If
the comma is missing and this isn't noticed, there will be an error.
Do:
my @list = (
"item1",
"item2",
"item3",
);
Don't:
my @list = (
"item1",
"item2",
"item3"
);
=item Last Statement in the Block
The same goes for C<;> in the last statement of the block. Almost
always add it even if it's not required, so when you add a new
statement you don't have to remember to add C<;> on a previous line.
Do:0
sub foo {
statement1;
statement2;
statement3;
}
Don't
sub foo {
statement1;
statement2;
statement3
}
=back
=head1 Function and Variable Prefixes Convention
=over 4
=item modperl_
The prefix for mod_perl C API functions.
=item MP_
The prefix for mod_perl C macros.
=item mpxs_
The prefix for mod_perl XS utility functions.
=item mp_xs_
The prefix for mod_perl I<generated> XS utility functions.
=item MPXS_
The prefix for mod_perl XSUBs with an XS() prototype.
=back
=head1 Coding Guidelines
The following are the Perl coding guidelines:
=head2 Global Variables
=over 4
=item avoid globals in general
=item avoid $&, $', $`
See C<Devel::SawAmpersand>'s I<README> that explains the evilness.
Under mod_perl everybody suffers when one is seen anywhere since the
interpreter is never shutdown.
=back
=head2 Modules
=over 4
=item Exporting/Importing
Avoid too much exporting/importing (glob aliases eat up memory)
When you do wish to import from a module try to use an explicit list or
tag whenever possible, e.g.:
use POSIX qw(strftime);
When you do not wish to import from a module, always use an empty list
to avoid any import, e.g.:
use IO::File ();
(explain how to use Apache::Status to find imported/exported
functions)
=back
=head2 Methods
=over 4
=item indirect vs direct method calls
Avoid indirect method calls, e.g.
Do:
CGI::Cookie->new
Don't:
new CGI::Cookie
=back
=head2 Inheritance
=over 4
=item Avoid inheriting from certain modules
Exporter.
To avoid inheriting B<AutoLoader::AUTOLOAD>
Do:
*import = \&Exporter::import;
Don't:
@MyClass::ISA = qw(Exporter);
=back
=head2 Symbol tables
=over 4
=item %main::
stay away from C<main::> to avoid namespace clashes
=back
=head2 Use of $_ in loops
Avoid using C<$_> in loops unless it's a short loop and you don't call
any subs from within the loop. If the loop started as short and then
started to grow make sure to remove the use of C<$_>:
Do:
for my $idx (1..100) {
....more than few lines...
foo($idx);
....
}
Don't:
for (1..100) {
....more than a few statements...
foo();
....
}
Because foo() might change C<$_> if foo()'s author didn't localize C<$_>.
This is OK:
for (1..100) {
.... a few statements with no subs called
# do something with $_
....
}
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
Stas Bekman E<lt>stas@stason.orgE<gt>
=head1 Authors
Stas Bekman E<lt>stas@stason.orgE<gt>
Doug MacEachern
=cut