Code Practices - keepcoding-tech/ctrl_nest GitHub Wiki

To maintain consistency, readability, and ease of collaboration, all contributors should follow these code practices when writing or modifying Perl.

Naming Conventions

  • Variables: use snake_case for variable names.

    my $user_id;
my $request_timeout;

  • Packages / Classes: use CamelCase for package and class names.

    package UserManager;
package RequestHandler;

  • Files: use CamelCase for .pm files:

    Auth.pm
Constants.pm

  • Files: use snake_case for .pl & .t files.

    auth.t          # test file
db_handler.pl   # perl script

Function Separation

Separate functions or subs in any file using a line of 80 hash (#) characters. This makes navigation and code scanning easier.

Example:

################################################################################

sub dns_resolution {
  my $hostname = 'perl.org';
  my $res      = Net::DNS::Resolver->new(nameservers => [qw(10.5.0.1)],);

  my $query = $res->search($hostname);

  if ($query) {
    foreach my $rr ($query->answer) {
      next unless $rr->type eq "A";
      say "Found an A record: " . $rr->address;
    }
  }
}

################################################################################

sub send_email {
  # first, create your message
  use Email::MIME;
  my $message = Email::MIME->create(
    header_str => [
      From    => '[email protected]',
      To      => '[email protected]',
      Subject => 'Happy birthday!',
    ],
    attributes => {
      encoding => 'quoted-printable',
      charset  => 'ISO-8859-1',
    },
    body_str => "Happy birthday to you!\n",
  );

  # send the message
  use Email::Sender::Simple qw(sendmail);
  sendmail($message);
}

################################################################################

Perl Best Practices (Beyond Formatting)

  • Use strict & warnings or Mojo::Base -strict: always include these pragmas to catch common bugs and unsafe constructs:

    use strict;
use warnings;

# or

use Mojo::Base -strict

  • Use my for Variable Declarations: always declare variables with my to ensure they have lexical scope.

    my $counter = 0;

  • Avoid Global Variables: global state can lead to unpredictable behavior. Keep variables scoped as tightly as possible.

  • Use undef Instead of Empty Strings for Optional Values: it makes intention clearer when a variable is explicitly "unset":

    my $value = undef;  # vs. my $value = '';

  • Return Early from Functions: simplify logic and reduce nesting by handling edge cases early:

    sub fetch_user {
  my ($id) = @_;
  return unless defined $id;
  ...
}

  • Use List Context Thoughtfully" be mindful of scalar vs. list context, especially when working with functions that behave differently in each:

    my @lines = <$fh>;       # list context
my $line_count = @lines;

Following these practices will help keep our codebase clean, consistent, and easy to work with. When in doubt, prioritize clarity and maintainability.

⚠️ **GitHub.com Fallback** ⚠️