My Coding Conventions

my_coding_conventions.md

My Coding Conventions

• Introduction
  • Comments vs. Commented-out Code
  • Comment tags / annotations
  • Boundary characters in output strings

Introduction

This document is an attempt at formalizing some coding guidelines I try to adhere to.

Comments vs. Commented-out Code

Comments to accompany code should always be followed by a space, to distinguish comments from commented out code.

Examples:

# This is a comment, perhaps with a code example
# $this->is_an_example()

#$this->is_commented_out_code();

Commented-out code should be kept to a minimum, since everything is under version control anyway, but sometimes it is practical, so just comment according to the above guidelines for easy identification.

Comment tags / annotations

There are many way to flag things in code for attention, follow-up or easy location.

Some examples lifted from Perl::Critic::Bangs::ProhibitFlagComments, which was an easy available list, the list was not compiled by me, but I have observed all the examples over time in different code bases.

XXX, TODO, FIXME, BUG, REVIEW

Decide on a common set of tags instead of just tagging in the wild. Tag with intent and tag properly.

I personally use the following:

• TODO, something need revisting or is not completely done
• REVIEW, something need to be revisited for review or inspection, perhaps a bug
• REF, point to an external reference or definition, like documentation or other URLs able to provide additional information, URLs are good, since most editors can open URLs directly

Examples:

# TODO: Fix variable names, they are too ambigous
foreach my $object (@data) {
    $object->calculate_deletion_date();
}

# REVIEW: What about using Time::Elapsed instead
printf "%d hours %d minutes and %d seconds\n",
    $seconds / (60 * 60), ($seconds % (60 * 60)) / 60, $seconds % 60;

# REVIEW: What about using Time::Elapsed instead
# REF: https://metacpan.org/pod/Time::Elapsed
printf "%d hours %d minutes and %d seconds\n",
    $seconds / (60 * 60), ($seconds % (60 * 60)) / 60, $seconds % 60;

Please note the colon after the tags, this is to distinguish from common use of the words resembling the tags, makes is easier to ack or grep.

Boundary characters in output strings

Very often we output strings either as log messages, error messages or other information. Notation used in these strings might not really matter, what I have observer however is that if these resemble code too much they might be confusing to the reader of the code.

Examples (in Perl):

Exposing the populated value of a variable / parameter

$log->info("Found value => $value for key => $key");

# Found value => bar for key => foo

The result of a calculation

print "Calculated sum = $sum\n";

# Calculated sum = 100

Where the value might be an empty string

print STDERR "Resolved state >$state<";

# Resolved state ><

Reading the code becomes harder an intent might be unclear, when comments output strings resembling source code constructs such as assignments.

The problem is of course that what we mean to convey, resembles constructs of code. The recommended pattern to use is to avoid common operators and idioms, for Perl a list could look as follows:

`:` over `=`, `=>`, `<`, `>`, `<<` and `>>`

The colon only clashes with labeled blocks, see Perl's goto, ref: http://perldoc.perl.org/functions/goto.html and since GOTO is not widely used this might be acceptable.

Another interesting problem is an often used idiom of indicating a empty string.

# $middlename might be empty
print STDERR "Received middlename >$middlename<";

# Received middlename ><

Here the recommended is the same, avoid common operators and idioms, for Perl a list could look as follows:

`«` and `»` over `'`, `<`, `>`, `<<`, `>>`, `(`, `)`, `{`, `}`, `[`, and `]`

# $middlename might be empty
print STDERR "Received middlename »$middlename«";

# Received middlename »«