Server IP : 85.193.89.191 / Your IP : 3.145.169.17 Web Server : Apache System : Linux 956367-cx40159.tmweb.ru 3.10.0-1160.105.1.el7.x86_64 #1 SMP Thu Dec 7 15:39:45 UTC 2023 x86_64 User : bitrix ( 600) PHP Version : 8.1.27 Disable Function : NONE MySQL : OFF | cURL : OFF | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /proc/978/cwd/usr/share/doc/perl-Cache-Cache-1.06/ |
Upload File : |
=========================== Coding style guidelines =========================== While there is no one ideal style in which to code, there are some advantages to adopting a common coding style. This guide helps outline the style for this project. ----------------------------- Tabs, spaces, and columns ----------------------------- Avoid tabs. Instead, use exactly 2 spaces to indent code. Lines should break at 80 columns. Whitespace greatly increases readability, and should be used between adjacent statements. The exceptions to the newline between statements rule include blocks of "use" statements and blocks of variable assignments. An example subroutine: sub build_something_else { my ( $self, $p_param ) = @_; Assert_Defined( $p_param ); return $self->calculate_something( $p_param + 1 ); } ----------------- Return Values ----------------- [Initially I advocated using a temporary variable to store the return value to increase code readability, but since reading and rereading (and re-rereading) Fowler's _Refactoring_, I am inclined to agree with him and now support the Remove Temp with Query refactoring, which also implies returning the result of a calculation directly] ---------- Naming ---------- The following naming conventions should be used: * Variables Inside routines, variables should be named "variable_name", all lowercase alphanumeric characters, with underscores separating the words. my $variable_name; Additionally, it is often a good idea to describe the type of the variable (other than scalars and object instances) in the name. Some examples follow: my $foo = 'foo'; my @number_list = ( 1, 2, 3 ); my $number_list_ref = [ 1, 2, 3 ]; my $number_list_ref = \@number_list; my %alphabet_hash = ( 'a' => 1, 'b' => 2 ); my $alphabet_hash_ref = { 'a' => 1, 'b' => 2 }; my $alphabet_hash_ref = \%alphabet_hash; my $file_cache = new Cache::FileCache( ); * Parameters Parameters should be prefixed with 'p_' to assist in readability. Note that I typically leave off the p_ for the $self parameter, and the $proto parameter in the constructor. For example: sub add { my ( $self, $p_value_one, $p_value_two ) = @_; return $p_value_one + $p_value_two; } * Public static class variables This type of variable is written "Public_Static_Class_Variable" and is accessible publicly, and can be updated at runtime. These variables are global for the scope of the module. Note that there are very few cases in which this type of variable should not be exposed via a class property (see below). my $Public_Static_Class_Variable; * Private static class variables This type of variable is written "_Private_Static_Class_Variable" and is accessible only to the module itself, and can be updated at runtime. Note that there are very few cases in which this type of variable should not be exposed via a class property (see below). my $_Private_Static_Class_Variable * Public static class constants This type of "variable" is written "PUBLIC_STATIC_CONSTANT" and it accessible publicly, and can not be modified at runtime. These constants are global for the scope of the module. It is often a good idea to make these constants available via Exporter as @EXPORT_OK. my $PUBLIC_STATIC_CONSTANT = 'foo'; * Private static class constants This type of "variable" is written "_PRIVATE_STATIC_CONSTANT" and is accessible only to the module itself, and can not be modified at runtime. These constants are global for the scope of the module. $_PRIVATE_STATIC_CONSTANT = 'foo'; * Public instance methods This type of subroutine is written as "public_instance_method" and takes $self as the first parameter. This is part of the public interface for a module, and should be documented with pod (see below for details about documentation). sub public_instance_method { my ( $self, $p_parameter ) = @_; } * Private instance methods This type of subroutine is written as "_private_instance_method" and takes $self as the first parameter. This is not part of the public interface, and can be documented inline with perl comments. sub _private_instance_method { my ( $self, $p_parameter ) = @_; } * Public class methods This type of subroutine is written "Public_Class_Method" and does not take $self as a parameter. This is part of the public interface for a module, and should be documented with pod (see below for details about documentation). You can optionally make use of the Static_Params method in CacheUtils to automatically shift the parameters if it is called via the class dereference operator rather that explicitly via the package's namespace. (i.e. it is called via Class->Public_Class_Method( ) vs. Class::Public_Class_Method( ) ). sub Public_Class_Method { my ( $p_parameter ) = Static_Params( @_ ); } * Private class methods This type of subroutine is written "_Private_Class_Method" and does not take $self as a parameter. This is not part of the public interface, and can be documented inline with perl comments. You can optionally make use of the Static_Params method in CacheUtils to automatically shift the parameters if it is called via the class dereference operator rather that explicitly via the package's namespace. (i.e. it is called via Class->Public_Class_Method( ) vs. Class::Public_Class_Method( ) ). sub _Private_Class_Method { my ( $p_parameter ) = Static_Params( @_ ); } -------------- Properties -------------- Properties and property accessor methods should be used to provide a consistent abstracted interface to certain types of data. In general, properties accessors are methods that take the form of get_property and set_property. Private getters or setters are written _get_property and _set_property respectively. Additionally, static class properties are written Get_Property and Set_Property as a method on the class itself. The properties are stored in the $self hash (assuming the object is a blessed hash) with a key that corresponds to the first letter uppercase name of the property, preceded by an underscore. An example of writing a scalar instance property "foo" with a public getter and a private setter: sub get_foo { my ( $self ) = @_; return $self->{_Foo}; } sub _set_foo { my ( $self, $foo ) = @_; $self->{_Foo} = $foo; } An example of writing a list instance property "bar_list" with a public getter and a public setter. sub get_bar_list { my ( $self ) = @_; return @{$self->{_Bar_List}}; } sub set_bar_list { my ( $self, @bar_list ) = @_; @{$self->{_Bar_List}} = @bar_list; } ----------------------------- Statement and brace style ----------------------------- * if/elsif/else statements if ( $condition ) { # ... } elsif ( $condition ) { # ... } else { # ... } * for loops for ( my $i; $i < 1000; $i++ ) { # ... } * foreach loops foreach my $foo ( @foo_list ) { # ... } * subroutines sub do_something { my ( $self ) = @_; #... return $foo; } * error handling my $foo = $self->get_foo( ) or throw Error( "Couldn't get foo" ); -------------------- Module structure -------------------- A the top of each module there should be a copyright disclaimer as follows: ###################################################################### # $ Id: $ # Copyright (C) 2002 John Smith All Rights Reserved # # Software distributed under the License is distributed on an "AS # IS" basis, WITHOUT WARRANTY OF ANY KIND, either expressed or # implied. See the License for the specific language governing # rights and limitations under the License. ###################################################################### The "Id" keyword is optional, though highly recommended if the code is being managed with CVS. After the copyright disclaimer, there should be a blank line, and then the package declaration: package Cache::FileCache; The "use" statements should be listed in alphabetical order, with the lowercase modules listed first. (This is so that "use strict" is the next line after the package declaration) use strict; use vars qw( @ISA @EXPORT_OK $PUBLIC_STATIC_CONSTANT ); use Cache::Cache qw( $EXPIRES_NEVER ); use Error; use Exporter; Next, list the @ISA and @EXPORT or @EXPORT_OK lists: @ISA = qw( Cache::Cache Exporter ); @EXPORT_OK = qw( $PUBLIC_STATIC_CONSTANT ); Followed by any variables in the "use vars" section: $PUBLIC_STATIC_CONSTANT = 'foo'; And any non exported, non "use vars" variables: my $_PRIVATE_STATIC_CONSTANT = 'bar'; my $_Private_Static_Class_Variable; Write the methods in the following order: * public class methods * private class methods * class properties ( first Get, then Set ) * new ( if the class is to be instantiated ) * public instance methods * private instance methods * instance properties ( first get, then set ) Finally, the class should be documented according to this template: __END__ =pod =head1 NAME Class -- short description with no line breaks =head1 DESCRIPTION Verbose description and overview of the class =head1 SYNOPSIS Example of the usage of the class =head1 METHODS =over 4 =item B<method_name( $p_parameter )> Description of the method =over 4 =item $p_parameter Description of the $p_parameter =item Returns Description of the return value =back =back =head1 PROPERTIES =over 4 =item B<(get|set)_foo> Description of foo =back =head1 SEE ALSO Related modules or documentation =head1 AUTHOR Original author: John Smith <jsmith@company.com> Last author: $ Author: $ Copyright (C) 2002 John Smith =cut