Versions Compared

Old Version 12

changes.mady.by.user Andrew Kurth

Saved on

compared with

New Version Current

changes.mady.by.user Andrew Kurth

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

The backend Perl code must conform to the following style guidelines. If you find any code which doesn't conform, please fix it. These requirements are intended to maintain consistent, organized, professional code.

Indentation

Proper indentation is very important.  Just because the code lines up properly in your editor of choice, does not mean it will line up properly for someone else working on the project.  This can be very annoying.

Tabs should be used to indent all code blocks.  Spaces should never be used to indent code blocks.  Mixing tabs and spaces results in misaligned code blocks for other developers who prefer different indentation settings.  Consider the following code block which is indented with all tabs (shown with and without whitespaces):

Indented properly with tabs.
Indentation width set to 3.
Whitespaces shown.

Code is lined up properly.

Indentation width changed to 8.
Code remains lined up properly.

Now consider a situation where another developer is using an editor which is configured to indent using spaces by default.  The developer makes changes to 1 of the lines:

Indented incorrectly with a mix of
tabs and spaces.

Code appears lined up to the
developer who messed up the
indentation.

Code is not lined up for other
developers.

A mix of tabs and spaces is only preferred in order to indent sections of code which span multiple lines but is not an entire block between curly braces.  The following example illustrates this:

Everything in the notify command is indented with a single tab.
The message is broken up into multiple lines for readability.
Each line of the message is indented with spaces to make it line up with the first line.

Code is lined up properly and easy to read.

The editor's indentation with is changed to 8.
The only shifts are reflected in the tabs.

The code remains lined up properly and easy to read.

Comments

Comment as much as sanely possible!

There should always be at least 1 space between the # character and the beginning of the comment.  This makes it a little easier to read multi-line comments:

No

Yes

#Comments are your friend, they help
#other developers understand your brilliance.

# Comments are your friend, they help
# other developers understand your brilliance.

Subroutine & Variable Names

Single letter variable names should never be used unless for a loop iterator:

No

Yes

OK

OK

my $m = '00:50:56:12:88:99';

my $mac_address = '00:50:56:12:88:99';

for (my $loop = 0; $loop<=10; $loop++) {

for (my $i = 0; $i<=10; $i++) {

Avoid abbreviations:

No

Yes

No

Yes

my $ip_addr;

my $ip_address;

sub get_comp_name {

sub get_computer_name {

Use underscores to separate words:

No

Yes

No

Yes

sub getcomputername {

sub get_computer_name {

my $endtime;

my $end_time;

All subroutine names should be entirely lowercase:

No

Yes

sub updateRequestState {

sub update_request_state {

All variable names defined in subroutines should entirely lowercase:

No

Yes

my $requestState;

my $request_state;

All class variables defined at the top of a .pm file should be entirely uppercase:

Yes

our $SOURCE_CONFIGURATION_DIRECTORY = "$TOOLS/Windows";

Never mix upper and lowercase:

No

Yes

my $ipAddress;

my $ip_address;

POD Documentation

All modules and subroutines must contain a POD documentation block describing what it does. POD is "Plain Old Documentation". For more information, see:

What is POD?: http://en.wikipedia.org/wiki/Plain_Old_Documentation
POD syntax guide: http://search.cpan.org/dist/perl/pod/perlpod.pod

Each subroutine should begin with a POD block with the following format:

Code Block
#/////////////////////////////////////////////////////////////////////////////

=head2 my_subroutine_name

 Parameters  : none
 Returns     : boolean
 Description : This is what the subroutine does. These lines must be 80
               characters or less. Additional lines must be indented with
               spaces, not tabs.

=cut

sub my_subroutine_name {

}
Generating or Checking POD

There are several utilities available for generating formatted POD documentation including pod2text and pod2html.  It is a good idea to run a module through one of these utilities before committing updates.

Curly Brackets, Parenthesis

There should be a space between every control/loop keyword and the opening parenthesis:

No

Yes

No

Yes

if($loop_count <= 10) {

if ($loop_count <= 10) {

while($loop_count <= 10) {

while ($loop_count <= 10) {

There should be a space between every closing parenthesis and the opening curly bracket:

No

Yes

No

Yes

if ($loop_count <= 10){

if ($loop_count <= 10) {

while ($loop_count <= 10){

while ($loop_count <= 10) {

If/Else Statements

'else' & 'elsif' statements should be on a separate line after the previous closing curly brace:

No

Yes

if ($end_time < $now) {
   ...
} else {
   ...
}

if ($end_time < $now) {
   ...
}
else {
   ...
}